X-Git-Url: https://git.gag.com/?a=blobdiff_plain;f=doc%2Fmanual%2Fstyle.txt;h=87b1e6babcd74baf19f8b743de1e4eb618907b8e;hb=09fbc0ab8649c69a9f97fa4ed599db836a2c0152;hp=ef73aed6e79f1c00dc09774bb1f26db74d4c2651;hpb=b11d79110ebea755d139406fa65e484cdc379cf0;p=fw%2Fopenocd

diff --git a/doc/manual/style.txt b/doc/manual/style.txt
index ef73aed6e..87b1e6bab 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,8 +66,9 @@ 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).
 
@@ -77,8 +78,11 @@ Finally, try to avoid lines of code that are longer than than 72-80 columns:
 - @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
+- 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
@@ -176,7 +180,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:
@@ -304,7 +308,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.
@@ -358,10 +362,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