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 87b1e6babcd74baf19f8b743de1e4eb618907b8e..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
@@ -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.