image_t -> struct image

[fw/openocd] / doc / manual / style.txt

diff --git a/doc/manual/style.txt b/doc/manual/style.txt
index c6dc3ca2531276219b6eca67d0673a5e15bef5ba..b6d68b48e9bd9691714545bfcd027fa241b3f24b 100644 (file)
--- 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:
@@ -80,6 +80,13 @@ Finally, try to avoid lines of code that are longer than than 72-80 columns:
 - variables declarations may be mixed with code
 - new block scopes for selection and iteration statements
 
+@section styletypes Type Guidelines
+- use native types (@c int or @c unsigned) if the type is not important
+  - if size matters, use the types from \<stdint.h\> or \<inttypes.h\>:
+    - @c int8_t, @c int16_t, @c int32_t, or @c int64_t: signed types of specified size
+    - @c uint8_t, @c uint16_t, @c uint32_t, or @c uint64_t: unsigned types of specified size
+  - do @b NOT redefine @c uN types from "types.h"
+
 @section stylefunc Functions
 
 - static inline functions should be prefered over macros:
@@ -99,6 +106,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
 
  */
@@ -128,7 +149,7 @@ 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
@@ -208,7 +229,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
@@ -323,7 +344,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.
@@ -337,10 +358,8 @@ 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