Index: work/doc/doxygen/doxygen.config =================================================================== --- work/doc/doxygen/doxygen.config (revision 7486) +++ work/doc/doxygen/doxygen.config (revision 7487) @@ -448,7 +448,7 @@ # scope will be included in the documentation. # The default value is: NO. -EXTRACT_PACKAGE = NO +EXTRACT_PACKAGE = YES # If the EXTRACT_STATIC tag is set to YES, all static members of a file will be # included in the documentation. @@ -741,7 +741,7 @@ # will automatically be disabled. # The default value is: YES. -WARN_IF_UNDOCUMENTED = YES +WARN_IF_UNDOCUMENTED = NO # If the WARN_IF_DOC_ERROR tag is set to YES, doxygen will generate warnings for # potential errors in the documentation, such as not documenting some parameters @@ -779,7 +779,7 @@ # messages should be written. If left blank the output is written to standard # error (stderr). -WARN_LOGFILE = +WARN_LOGFILE = doxygen.warnings.log #--------------------------------------------------------------------------- # Configuration options related to the input files @@ -2002,7 +2002,7 @@ # The default value is: NO. # This tag requires that the tag ENABLE_PREPROCESSING is set to YES. -MACRO_EXPANSION = NO +MACRO_EXPANSION = YES # If the EXPAND_ONLY_PREDEF and MACRO_EXPANSION tags are both set to YES then # the macro expansion is limited to the macros specified with the PREDEFINED and @@ -2051,7 +2051,7 @@ # definition found in the source code. # This tag requires that the tag ENABLE_PREPROCESSING is set to YES. -EXPAND_AS_DEFINED = +EXPAND_AS_DEFINED = HT # If the SKIP_FUNCTION_MACROS tag is set to YES then doxygen's preprocessor will # remove all references to function-like macros that are alone on a line, have Index: work/doc/doxygen/src_plugins/propedit/propedit.dox =================================================================== --- work/doc/doxygen/src_plugins/propedit/propedit.dox (revision 7486) +++ work/doc/doxygen/src_plugins/propedit/propedit.dox (revision 7487) @@ -3,29 +3,55 @@ \fn int propedit_action(int argc, const char **argv, pcb_coord_t x, pcb_coord_t y); - Runs the Property Editor dialog after populating it with properties of selected objects. + Runs the Property Editor dialog (\ref dlg_propedit.c) after populating it with properties of selected objects. - Calls \ref pcb_propsel_map_core. - \remark Parameters are not used. They are there only to fulfill the function prototype. + This function holds a \ref pe_ctx_t context during dialog existence, and dispatches + user events (add, modify...) to the `props` list, using the \ref sect_props_string_api. + Calls \ref pcb_propsel_map_core, and GUI virtual functions + \ref hid_s::propedit_start and \ref hid_s::propedit_end. + + \remark Parameters are not used. They are there, only to fulfill the function prototype. + \return 0 if OK, 1 if there's no GUI or the active GUI can't edit properties. \fn int propset_action (int argc, const char **argv, pcb_coord_t x, pcb_coord_t y); - Sets _value_ for a named _prop_erty of objects selected set. + Sets _value_ for a named _prop_ property on objects of selected set. Calls \ref pcb_propsel_set (argv[0], argv[1]); - \todo the \c printf statements should be issued only in DEBUG mode ? + \todo Should the \c printf statements be issued only in DEBUG mode ? - \param argc The number of arguments in \p argv. Should be at least 2 ? \todo CHECK - \param x, y Unused. - \return 0 + \param argc The number of arguments in \p argv. Should be at least 2, here. + \param x, y Unused. + \return 0 +\todo The code checking \p argc is commented. Better check is needed ? Uncomment ? + \fn pcb_uninit_t hid_propedit_init (void); - Calls PCB_REGISTER_ACTIONS(propedit_action_list, propedit_cookie) - \todo I(Alain) find the macro PCB_REGISTER_ACTIONS misleading - as it appears line 82, is redefined, and called again line 92 ! :( + Registers the propedit plug-in. + Calls PCB_REGISTER_ACTIONS(propedit_action_list, propedit_cookie) after + `#include "dolists.h"` + which is equivalent to this code: + \code + {extern void register_propedit_action_list(); register_propedit_action_list();} + \endcode + after the function: + \code + void register_propedit_action_list () + { pcb_hid_register_actions(propedit_action_list, sizeof(propedit_action_list)/sizeof(propedit_action_list[0]), propedit_cookie, 0); + } + \endcode + has been declared thanks to \ref hid.c `PCB_REGISTER_ACTIONS` macro expansion. + \see pcb_hid_register_actions. + \return The function to be called when the action ends. See \ref pcb_hid_remove_actions_by_cookie + */ + +/** PCB_REGISTER_ACTIONS macro in \ref hid.c will create this function. */ +void register_propedit_action_list () +{ pcb_hid_register_actions(propedit_action_list, sizeof(propedit_action_list)/sizeof(propedit_action_list[0]), propedit_cookie, 0); +} Index: work/doc/doxygen/src_plugins/propedit/props.dox =================================================================== --- work/doc/doxygen/src_plugins/propedit/props.dox (revision 7486) +++ work/doc/doxygen/src_plugins/propedit/props.dox (revision 7487) @@ -1,11 +1,24 @@ /** \file props.c \brief Builds and maintains a collection of values for each named property. + Refer to + `pcb-rnd` [propedit] feature. + + _attribute_ and _property_ are both textual `key=value` pairs. `pcb-rnd` + has its own internal properties such as `width=1.0mm` for example. + The user might wish to add an attribute with the same key, `width`. + It is allowed, thanks to the following name space split convention: + - an _attribute_ is a user property + - a _core property_ is a `pcb-rnd` internally managed property. + + In this documentation, the term _property_ may describe an _attribute_ or a + _core property_. + A property list (props) is a string-keyed hash table of type \ref htsp_t. - Each entry in this table is a named property with a value that is a type - and a value hash (_vhash_). Refer to \ref htsp_entry_t. - - _vhash_'s key is each value that the property ever took + Each entry in this table (refer to \ref htsp_entry_t) is a named property + with a value that is a type, and a value hash (_vhash_). + - _vhash_'s key is each value that the property ever took. - _vhash_'s value is an integer value of how many times the given property is taken. A value can be added any time using \ref pcb_props_add. @@ -18,10 +31,28 @@ - all known values of a property \ref pcb_props_get - statistics of values of a property \ref pcb_props_stat - A _core_ property is one handled by, and directly created, from pcb-rnd. - A non-core property is one added by the user. + \section sect_props_string_api Query String-API + To communicate action intent, a small commands list is designed: + Command name | Description + ----------------|-------------- + `v1st` | Gets the _first_ value + `vnxt` | Gets the _next_ value + `vset` | Sets the property. See \ref pcb_propsel_set + `vdel` | Deletes this property. See \ref pcb_propsel_del + `type` | Property type is requested + Examples: + \code + Explain, and link. + \endcode + + \section sect_props_pe_ctx_t Property Editor Context + Some of the functions needs an instance of \ref pe_ctx_t. This instance is + totally out of the scope of props.c, and is currently held by \ref pcb_gtk_dlg_propedit_t. + \todo How to get it from ? somewhere ? API ? + + \fn htsp_t *pcb_props_init(void); Starts a new list of properties. Use \ref pcb_props_uninit to free the list. \return A newly allocated string-keyed hash table. @@ -60,29 +91,29 @@ pcb_propval_t *most_common, pcb_propval_t *min, pcb_propval_t *max, pcb_propval_t *avg); Looks up property \p propname in all \p props, and calculates statistics - for all values occured so far. - - min, max, avg are meaningful only for numeric value types. + for all values occured so far. A statistic (\p min, \p max or \p avg) + is requested if its input pointer is not NULL. - Invalid type/stat combinations: - type=string min, max, avg Q:Alain->Igor2 : Do you mean when type=string, min, max, avg = NULL ? + \p min, \p max, \p avg are meaningful outputs, only for numeric value types. \param [out] min, max, avg The statistic results. - \param [out] most_common ? a string ? + \param [out] most_common The "best result". Need an example here. \param [in] most_common, min, max, avg Pointers to value holder. Can be \c NULL. - \return \c NULL if \p propname doesn't exist or stat values that - can not ? be calculated for the given type are not \c NULL. ? - Your comments are ... not so clear. Need to sort this out. + \return \c NULL if \p propname doesn't exist or \p propname is a string + and stats are requested (\p min, \p max or \p avg is not NULL). + Otherwise, returns the property structure found. \fn const char *propedit_query(void *pe, const char *cmd, const char *key, const char *val, int idx); - ?? String query API for HIDs to call back without having to link... ? + This function implements a \ref sect_props_string_api for HIDs to call back without + having to link this file... - \param pe a \ref pe_ctx_t property editor context. \todo should be pe_ctx_t i.s.o **void** here ? - \param cmd There seems to have conventions for commands... Need to document somewhere. Is it in dev corner ? + \param pe Needs to map a \ref pe_ctx_t property editor context. + \param cmd Command. See \ref sect_props_string_api. \param key, val Queries for these key, val ? - \param idx Unused ? - \return \c NULL as an invalid query ; else ? + \param idx Unused + \return \c NULL as an invalid query ; \c NULL for most of the actions ; + a one character coded type if "type" is queried. \fn const char *propedit_sprint_val(pcb_prop_type_t type, pcb_propval_t val); @@ -93,16 +124,27 @@ \fn void propedit_ins_prop(pe_ctx_t *ctx, htsp_entry_t *pe); - Adds a row at the end of the GUI Property Editor table, using \p pe property info. + Adds a row at the end of the GUI Property Editor table, using \p pe + property entry info. - \param ctx A Property Editor context. - \todo Not consistent here, as \ref pe_ctx_t is "for internal use only", and - there is no API to retrieve it !? -*/ + \param ctx A Property Editor context. See \ref sect_props_pe_ctx_t. + */ +/** \file props.c + \note I suggest renaming: + old | new + --------------------|------------- + pcb_props_get | pcb_prop_get + pcb_props_add | pcb_prop_add + pcb_props_type_name | pcb_prop_type_name + pcb_props_stat | pcb_prop_stat + */ + + /** \file props.h - Header file for \ref props.c + \brief Header file for \ref props.c + \enum pcb_prop_type_t A property type list, including string, integer, etc... \var PCB_PROPT_invalid @@ -115,65 +157,22 @@ Can hold the property value. - \struct pcb_props_t + \struct pcb_props_t A single property, as a combination of a property type and property values. + \todo if really it is a single property, why not renaming it `pcb_prop_t` ? \var pcb_props_t::core - 1 if it is a core property... Q:Alain->Igor2 : What is it used for ? + `1` if it is a _core property_. \typedef pe_ctx_t - for internal use. Keeps track of Property Editor context. - */ + Keeps track of Property Editor context (for internal use). -/** \todo Move those lines in htsp.dox file */ -/** \file htsp.c - A string-keyed hash table. - */ -/** An entry in a string-keyed hash table. */ -typedef struct { - int flag; - unsigned int hash; - htsp_key_t key; - htsp_value_t value; -} htsp_entry_t; - -/** The string-keyed hash table structure. - - Macro generated typedef : - \see src_3rd/liblihata/genht/htsp.h + \def HT(x) + Use generic to provide `htprop_[t|entry_t]` structures. + \remark This comment is not making its way to HTML doc. The only way I did succeed is commenting just above the #define in .h file */ -typedef struct { - unsigned int mask; - unsigned int fill; - unsigned int used; - htsp_entry_t *table; - unsigned int (*keyhash)(htsp_const_key_t); - int (*keyeq)(htsp_const_key_t, htsp_const_key_t); -#ifdef GENHT_USER_FIELDS - GENHT_USER_FIELDS -#endif -} htsp_t; - - -typedef struct { - int flag; - unsigned int hash; - htprop_key_t key; - htprop_value_t value; -} htprop_entry_t; - -typedef struct { - unsigned int mask; - unsigned int fill; - unsigned int used; - htprop_entry_t *table; - - unsigned int (*keyhash)(htprop_const_key_t); - int (*keyeq)(htprop_const_key_t, htprop_const_key_t); -#ifdef GENHT_USER_FIELDS - GENHT_USER_FIELDS -#endif -} htprop_t; +/** Use generic to provide `htprop_[t|entry_t]` structures. */ +#define HT(x) htprop_ ## x Index: work/doc/doxygen/src_plugins/propedit/propsel.dox =================================================================== --- work/doc/doxygen/src_plugins/propedit/propsel.dox (revision 7486) +++ work/doc/doxygen/src_plugins/propedit/propsel.dox (revision 7487) @@ -1,22 +1,26 @@ /** \file propsel.c \brief Builds a property list by looking at all selected objects on a design. - Syntax definition: - - attribute : "a/" + \c element + "/" + \c property - - property : "p/" + \c element + "/" + \c property + ... ? + `property` syntax definition as a regular expression: + \code + ^(a|p)(\/[^\/]+)* + \endcode + A property is an attribute `a/`, or core property `p/` followed by path + \c elements, separated by `/` character. - - \c element is \c line, \c trace, \c text ... - - \c property is \c rotation, ... + \c element could be \c line, \c trace, \c rotation, \c text ... - Q:Alain->Igor2 : Why the att AND prop ? To me they are synonyms. What difference do you make ? + Example: + \code + p/arc/angle/delta + \endcode + \fn void pcb_propsel_map_core(htsp_t *props); Loops through all PCB elements to only populate the selected elements properties in \p props Hash Table. - Q:Alain->Igor2 : Why \c _core in name ? - \fn int pcb_propsel_set(const char *prop, const char *value); Loops through all PCB elements to only set property \p value to \p prop on selected elements. @@ -41,4 +45,9 @@ \typedef del_ctx_t Used to keep track of \ref pcb_propsel_del operations. + + + \def DONE + Returns from function, after performing undo clean-up and counter increment. + */