Hi all, For my next trick with my Surpass tool, I intend to try and bring more uniformity to the various OpenOCD APIs. This primarily translates to renaming functions such that they group and sort better, but it should also involve structure and enum names. We could even go so far replace instances of 'struct blah *' and 'blah_t *' with new 'blah_p' types.
These kinds of transformations can be turned into a new chain of patch series, by providing a list of simple search and replace expressions. Examples of these expressions are provided in the commit comments of my recent series of patches, though most of those are probably more complex than what will be needed for this type of simple symbol rework. Please reply to this thread with suggestions for symbols changes that can be accomplished in this manner. Specifically, please provide lines of text that meet following the criteria: 0) Two columns of text, separated by a TAB character: 1) Column 1: regex suitable for grep and LHS of "sed -e 's,LHS,RHS,g'" 2) Column 2: pattern suitable for RHS of "sed -e 's,LHS,RHS,g'" For example, I have the following symbols on my hit list already, which should come through in this required format (attach it, if in doubt): jtag_register_event_callback jtag_event_callback_register jtag_unregister_event_callback jtag_event_callback_unregister jtag_call_event_callback jtag_event_callbacks_run These changes reflect a very simple heuristic: name components should be ordered from the most general to most specific. The following naming schemes should demonstrate this model with more clarity: module_noun_verb module_primary_secondary_verb module_primary_secondary_phase_step module_structure_field_verb With this scheme, related symbols will be grouped properly when sorted in the documentation. By extension, this will help developers learning the code, because names will become easily derivable from related constructs. I can provide numerous other examples in the code where this general guideline could be followed, but I can also find places where it would be idiosyncratic when applied. Put another way, this rule does not suffice on its own, but I think it worth giving some consideration before the 0.2.0 release. While each function merits independent consideration for its name, this heuristic provides a unified style with some clear benefits, but other schemes would work. We need to have agreed upon these high-level standards before the repository sees any renaming changes committed, and I this will emerge from the suggestions provided under this thread. I hope the community contributes ideas, so I can collate the feedback into appropriate series scripts. This may be a Sisyphean task overall, but the low-hanging fruit are overripe and must be picked to avoid rot. Cheers, Zach _______________________________________________ Openocd-development mailing list Openocd-development@lists.berlios.de https://lists.berlios.de/mailman/listinfo/openocd-development
