doxygen: fix issues with recent Doxygen versions

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

diff --git a/doc/manual/style.txt b/doc/manual/style.txt
index 71bb5f6bc18243d5759eba60dcf2bf5773cba519..0bfae35f70fe33085aa3d5430d853a9d530e3e70 100644 (file)
--- 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
@@ -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
@@ -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.