X-Git-Url: https://review.openocd.org/gitweb?p=openocd.git;a=blobdiff_plain;f=doc%2Fmanual%2Fstyle.txt;h=e654be9c3414986d533dca76ea47a593634815bf;hp=71bb5f6bc18243d5759eba60dcf2bf5773cba519;hb=6e9571164b4461dde96201a0676783c60151642f;hpb=060980357df2f71b8d18eb6a86a8c9878a8b417e

diff --git a/doc/manual/style.txt b/doc/manual/style.txt
index 71bb5f6bc1..e654be9c34 100644
--- a/doc/manual/style.txt
+++ b/doc/manual/style.txt
@@ -72,12 +72,31 @@ Finally, try to avoid lines of code that are longer than than 72-80 columns:
 - 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 @})
+- 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
@@ -93,7 +112,7 @@ pthreads require modest and predictable stack usage.
 
 @section stylefunc Functions
 
-- static inline functions should be prefered over macros:
+- static inline functions should be preferred over macros:
 @code
 /** do NOT define macro-like functions like this... */
 #define CUBE(x) ((x) * (x) * (x))
@@ -157,10 +176,10 @@ comments.
  * @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
@@ -182,7 +201,7 @@ The following guidelines apply to all Doxygen comment blocks:
   -# @c struct_name::member_name should be used to reference structure
     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
+  -# new pages can be linked into the hierarchy by using the @c \@subpage
     command somewhere the page(s) under which they should be linked:
   -# use @c \@ref in other contexts to create links to pages and sections.
 -# Use good Doxygen mark-up:
@@ -214,7 +233,7 @@ documentation as part of standalone text files:
   - Doxygen creates such pages for files automatically, but no content
     will appear on them for those that only contain manual pages.
   - The \@file block should provide useful meta-documentation to assist
-    techincal writers; typically, a list of the pages that it contains.
+    technical writers; typically, a list of the pages that it contains.
   - For example, the @ref styleguide exists in @c doc/manual/style.txt,
     which contains a reference back to itself.
 -# The \@file and \@page commands should begin on the same line as
@@ -242,7 +261,7 @@ The User's Guide is there to provide two basic kinds of information.  It
 is a guide for how and why to use each feature or mechanism of OpenOCD.
 It is also the reference manual for all commands and options involved
 in using them, including interface, flash, target, and other drivers.
-At this time, it is the only user-targetted documentation; everything
+At this time, it is the only documentation for end users; everything
 else is addressing OpenOCD developers.
 
 There are two key audiences for the User's Guide, both developer based.
@@ -308,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.
@@ -370,7 +389,7 @@ Maintainers must also be sure to follow additional guidelines:
 
 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.