On Sun, 2009-05-31 at 16:37 -0700, Zach Welch wrote:
> Hi all,
>
> The following things nagged at me when I did the target_type clean-up:
>
> 1) Remove redundant structure typedefs:
> a) Entails the following steps (for each named struct "type"):
> i) s/^typedef struct type_s/struct type_s/
> ii) s/^} type_t;/};/
> iii) s/type_t/struct type_s/
> iv) Fix any messes that these commands miss or make. ;)
> b) Eliminates what are essentially duplicated symbols:
> - simplifies the Doxygen documentation tremendously.
> - eliminates style ambiguity and forward referencing.
Attached is a quick attempt at a patch for the C Style Guide to add a
section for "Structure Guidelines", covering the above ideas.
Cheers,
Zach
Index: doc/manual/style.txt
===================================================================
--- doc/manual/style.txt (revision 1971)
+++ doc/manual/style.txt (working copy)
@@ -66,7 +66,6 @@
- most identifiers must use lower-case letters (and digits) only.
- macros must use upper-case letters (and digits) only.
- OpenOCD identifiers should NEVER use @c MixedCaps.
-- structure names must end with the '_s' suffix.
- typedef names must end with the '_t' suffix.
- use underline characters between consecutive words in identifiers
(e.g. @c more_than_one_word).
@@ -80,6 +79,27 @@
- variables declarations may be mixed with code
- new block scopes for selection and iteration statements
+...@section stylestruct Structure Guidelines
+
+Structures should be defined using the guidelines in this section.
+
+- Declare structures like the following example:
+...@verbatim
+/**
+ * Description of the reason for needing foo.
+ */
+struct foo {
+ int bar;
+};
+...@endverbatim
+ - Always refer to this as <code>struct foo</code>.
+ - Do @b not declare a @c typedef equivalent to the structure.
+ - Always refer to pointers as <code>struct foo *</code>.
+ - Do @b not declare a @c typedef for a pointer to the structure.
+- Structure names should be simple, without any suffix:
+ - All references to these names @a must be prefixed by @c struct,
+ - Any suffix (e.g. @c _s) appears redundant and should be removed.
+
@section stylefunc Functions
- static inline functions should be prefered over macros:
_______________________________________________
Openocd-development mailing list
Openocd-development@lists.berlios.de
https://lists.berlios.de/mailman/listinfo/openocd-development
