X-Git-Url: https://review.openocd.org/gitweb?p=openocd.git;a=blobdiff_plain;f=doc%2Fmanual%2Fstyle.txt;h=0bfae35f70fe33085aa3d5430d853a9d530e3e70;hp=b9a7612f0e85225e1b1bda4827f51672a36e403a;hb=ab597027ea98d4fa39980f9674dced42b5193b79;hpb=c5de7b6bd702e90bfd69d1c2efdd81713aefb191;ds=sidebyside

diff --git a/doc/manual/style.txt b/doc/manual/style.txt
index b9a7612f0e..0bfae35f70 100644
--- a/doc/manual/style.txt
+++ b/doc/manual/style.txt
@@ -49,7 +49,7 @@ OpenOCD project.
 - limit adjacent empty lines to at most two (2).
 - remove any trailing empty lines at the end of source files
 - do not "comment out" code from the tree; instead, one should either:
-  -# remove it entirely (Subversion can retrieve the old version), or
+  -# remove it entirely (git can retrieve the old version), or
   -# use an @c \#if/\#endif block.
 
 Finally, try to avoid lines of code that are longer than than 72-80 columns:
@@ -66,19 +66,42 @@ Finally, try to avoid lines of code that are longer than than 72-80 columns:
 - 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.
+- @c typedef names must end with the '_t' suffix.
+  - This should be reserved for types that should be passed by value.
+  - Do @b not mix the typedef keyword with @c struct.
 - use underline characters between consecutive words in identifiers
   (e.g. @c more_than_one_word).
 
+@section style_include_guards Include Guards
+
+Every header file should have a unique include guard to prevent multiple
+inclusion.
+To guarantee uniqueness, an include guard should be based on the filename and
+the full path in the project source tree.
+
+For the header file src/helper/jim-nvp.h, the include guard would look like
+this:
+
+@code
+#ifndef OPENOCD_HELPER_JIM_NVP_H
+#define OPENOCD_HELPER_JIM_NVP_H
+
+/* Your code here. */
+
+#endif /* OPENOCD_HELPER_JIM_NVP_H */
+@endcode
+
 @section stylec99 C99 Rules
 
 - inline functions
 - @c // comments -- in new code, prefer these for single-line comments
 - trailing comma allowed in enum declarations
-- designated initializers (@{ .field = value @})
-- variables declarations may be mixed with code
+- designated initializers ( .field = value )
+- variables declarations should occur at the point of first use
 - new block scopes for selection and iteration statements
+- use malloc() to create dynamic arrays. Do @b not use @c alloca
+or variable length arrays on the stack. non-MMU hosts(uClinux) and
+pthreads require modest and predictable stack usage.
 
 @section styletypes Type Guidelines
 - use native types (@c int or @c unsigned) if the type is not important
@@ -106,6 +129,20 @@ int f(int x1, int x2)
 	int y = f(x1, x2 - x1);
 	...
 }
+@endcode
+- Separate assignment and logical test statements.  In other words, you
+should write statements like the following:
+@code
+// separate statements should be preferred
+result = foo();
+if (ERROR_OK != result)
+	...
+@endcode
+More directly, do @b not combine these kinds of statements:
+@code
+// Combined statements should be avoided
+if (ERROR_OK != (result = foo()))
+	return result;
 @endcode
 
  */
@@ -135,14 +172,14 @@ comments.
  * in blocks such as the one in which this example appears in the Style
  * Guide.  See the Doxygen Manual for the full list of commands.
  *
- * @param foo For a function, describe the parameters (e.g. @a foo). 
+ * @param foo For a function, describe the parameters (e.g. @a foo).
  * @returns The value(s) returned, or possible error conditions.
  */
 @endverbatim
-  -# The block should start on the line following the opening @c /**.
-  -# The end of the block, \f$*/\f$, should also be on its own line.
+  -# The block should start on the line following the opening @c /\**.
+  -# The end of the block, @c *‍/, should also be on its own line.
   -# Every line in the block should have a @c '*' in-line with its start:
-    - A leading space is required to align the @c '*' with the @c /** line.
+    - A leading space is required to align the @c '*' with the @c /\** line.
     - A single "empty" line should separate the function documentation
       from the block of parameter and return value descriptions.
     - Except to separate paragraphs of documentation, other extra
@@ -162,7 +199,7 @@ The following guidelines apply to all Doxygen comment blocks:
   -# @c function_name() can be used to reference functions
     (e.g. flash_set_dirty()).
   -# @c struct_name::member_name should be used to reference structure
-    fields in the documentation (e.g. @c flash_driver_s::name).
+    fields in the documentation (e.g. @c flash_driver::name).
   -# URLS get converted to markup automatically, without any extra effort.
   -# new pages can be linked into the heirarchy by using the @c \@subpage
     command somewhere the page(s) under which they should be linked:
@@ -215,7 +252,7 @@ This file contains the @ref pagename page.
 @endverbatim
 
 For an example, the Doxygen source for this Style Guide can be found in
-@c doc/manual/style.txt, alongside other parts of The Manual.  
+@c doc/manual/style.txt, alongside other parts of The Manual.
 
  */
 /** @page styletexinfo Texinfo Style Guide
@@ -290,7 +327,7 @@ For technical reference material:
    - Else it's a "Config Command" if it must be used before the
      configuration stage completes.
    - For a "Driver", list its name.
-   - Use BNF style regular expressions to define parameters:
+   - Use EBNF style regular expressions to define parameters:
      brackets around zero-or-one choices, parentheses around
      exactly-one choices.
    - Use \@option, \@file, \@var and other mechanisms where appropriate.
@@ -330,7 +367,7 @@ Likewise, the @ref primerlatex for using this guide needs to be completed.
 This page provides some style guidelines for using Perl, a scripting
 language used by several small tools in the tree:
 
--# Ensure all Perl scripts use the proper suffix (@c .pl for scripts, and 
+-# Ensure all Perl scripts use the proper suffix (@c .pl for scripts, and
    @c .pm for modules)
 -# Pass files as script parameters or piped as input:
   - Do NOT code paths to files in the tree, as this breaks out-of-tree builds.
@@ -344,17 +381,15 @@ perl script.pl
 
 Maintainers must also be sure to follow additional guidelines:
 -# Ensure that Perl scripts are committed as executables:
-  - Use "<code>chmod +x script.pl</code>"
-    @a before using "<code>svn add script.pl</code>", or
-  - Use "<code>svn ps svn:executable '*' script.pl</code>"
-    @a after using "<code>svn add script.pl</code>".
+    Use "<code>chmod +x script.pl</code>"
+    @a before using "<code>git add script.pl</code>"
 
  */
 /** @page styleautotools Autotools Style Guide
 
 This page contains style guidelines for the OpenOCD autotools scripts.
 
-The following guidelines apply to the @c configure.in file:
+The following guidelines apply to the @c configure.ac file:
 - Better guidelines need to be developed, but until then...
 - Use good judgement.