- 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).
+@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 @})
-- variables declarations may be mixed with code
+- 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
+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
@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))
* @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
-# @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
+ -# 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:
- 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
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.
- 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.
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.
Code Review / openocd.git / blobdiff