-/** @page styleguide OpenOCD Coding C Style Guide
+/** @page styleguide Style Guides
-The following rules describe a formatting, naming, and other conventions
-that should be followed when writing or changing the OpenOCD C code.
-Many of the general rules should apply to OpenOCD's Jim/TCL code as well.
-
-The goals of this guide are:
-- to produce code that appears clean, consistent, and readable,
-- to allow developers to create patches that conform to a standard,
+The goals for each of these guides are:
+- to produce correct code that appears clean, consistent, and readable,
+- to allow developers to create patches that conform to a standard, and
- to eliminate these issues as points of future contention.
-consistent.
Some of these rules may be ignored in the spirit of these stated goals;
however, such exceptions should be fairly rare.
-@section styleformat Formatting Rules
+The following style guides describe a formatting, naming, and other
+conventions that should be followed when writing or changing the OpenOCD
+code:
+
+- @subpage styletcl
+- @subpage stylec
+- @subpage styleperl
+- @subpage styleautotools
+
+In addition, the following style guides provide information for
+providing documentation, either as part of the C code or stand-alone.
+
+- @subpage styledoxygen
+- @subpage styletexinfo
+- @subpage stylelatex
+
+Feedback would be welcome to improve the OpenOCD guidelines.
+
+ */
+/** @page styletcl TCL Style Guide
+
+OpenOCD needs to expand its Jim/TCL Style Guide.
+
+Many of the guidelines listed on the @ref stylec page should apply to
+OpenOCD's Jim/TCL code as well.
+
+ */
+/** @page stylec C Style Guide
+
+This page contains guidelines for writing new C source code for the
+OpenOCD project.
+
+@section styleformat Formatting Guide
- remove any trailing white space at the end of lines.
- use TAB characters for indentation; do NOT use spaces.
- 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
- -# use an @c #if/#endif block.
+ -# 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:
- 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).
- 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
+ - if size matters, use the types from \<stdint.h\> or \<inttypes.h\>:
+ - @c int8_t, @c int16_t, @c int32_t, or @c int64_t: signed types of specified size
+ - @c uint8_t, @c uint16_t, @c uint32_t, or @c uint64_t: unsigned types of specified size
+ - do @b NOT redefine @c uN types from "types.h"
@section stylefunc Functions
...
}
@endcode
+- Separate assignment and logical test statements. In other words, you
+should write statements like the following:
+@code
+// separate statements should be preferred
+result = foo();
+if (ERROR_OK != result)
+ ...
+@endcode
+More directly, do @b not combine these kinds of statements:
+@code
+// Combined statements should be avoided
+if (ERROR_OK != (result = foo()))
+ return result;
+@endcode
+
+ */
+/** @page styledoxygen Doxygen Style Guide
+
+The following sections provide guidelines for OpenOCD developers
+who wish to write Doxygen comments in the code or this manual.
+For an introduction to Doxygen documentation,
+see the @ref primerdoxygen.
+
+@section styledoxyblocks Doxygen Block Selection
-@section styledoxygen Doxygen Rules
+Several different types of Doxygen comments can be used; often,
+one style will be the most appropriate for a specific context.
+The following guidelines provide developers with heuristics for
+selecting an appropriate form and writing consistent documentation
+comments.
-- use @c /// to for one-line documentation
-- for multiple lines, use a "block" style with one space
+-# use @c /// to for one-line documentation of instances.
+-# for documentation requiring multiple lines, use a "block" style:
@verbatim
/**
- * @brief Short description.
- * Full description here.
- * @param foo Describe foo.
+ * @brief First sentence is short description. Remaining text becomes
+ * the full description block, where "empty" lines start new paragraphs.
+ *
+ * One can make text appear in @a italics, @b bold, @c monospace, or
+ * in blocks such as the one in which this example appears in the Style
+ * Guide. See the Doxygen Manual for the full list of commands.
+ *
+ * @param foo For a function, describe the parameters (e.g. @a foo).
+ * @returns The value(s) returned, or possible error conditions.
*/
@endverbatim
-- if the total line length will be less than 72 columns, then
+ -# 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.
+ -# 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 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
+ "empty" lines should be removed from the block.
+ -# Only single spaces should be used; do @b not add mid-line indentation.
+-# If the total line length will be less than 72-80 columns, then
- The @c /**< form can be used on the same line.
- This style should be used sparingly; the best use is for fields:
- - @code int field /**< field description */ @endcode
+ @code int field; /**< field description */ @endcode
+
+@section styledoxyall Doxygen Style Guide
+
+The following guidelines apply to all Doxygen comment blocks:
+
+-# Use the @c '\@cmd' form for all doxygen commands (do @b not use @c '\\cmd').
+-# Use symbol names such that Doxygen automatically creates links:
+ -# @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::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:
+ -# use @c \@ref in other contexts to create links to pages and sections.
+-# Use good Doxygen mark-up:
+ -# '\@a' (italics) should be used to reference parameters (e.g. <i>foo</i>).
+ -# '\@b' (bold) should be used to emphasizing <b>single</b> words.
+ -# '\@c' (monospace) should be used with <code>file names</code> and
+ <code>code symbols</code>, so they appear visually distinct from
+ surrounding text.
+ -# To mark-up multiple words, the HTML alternatives must be used.
+-# Two spaces should be used when nesting lists; do @b not use '\\t' in lists.
+-# Code examples provided in documentation must conform to the Style Guide.
+
+@section styledoxytext Doxygen Text Inputs
+
+In addition to the guidelines in the preceding sections, the following
+additional style guidelines should be considered when writing
+documentation as part of standalone text files:
+
+-# Text files must contain Doxygen at least one comment block:
+ -# Documentation should begin in the first column (except for nested lists).
+ -# Do NOT use the @c '*' convention that must be used in the source code.
+-# Each file should contain at least one @c \@page block.
+ -# Each new page should be listed as a \@subpage in the \@page block
+ of the page that should serve as its parent.
+ -# Large pages should be structure in parts using meaningful \@section
+ and \@subsection commands.
+-# Include a @c \@file block at the end of each Doxygen @c .txt file to
+ document its contents:
+ - 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.
+ - 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
+ the start of the Doxygen comment:
+@verbatim
+/** @page pagename Page Title
+
+Documentation for the page.
+
+ */
+/** @file
+
+This file contains the @ref pagename page.
+
+ */
+@endverbatim
+
+For an example, the Doxygen source for this Style Guide can be found in
+@c doc/manual/style.txt, alongside other parts of The Manual.
+
+ */
+/** @page styletexinfo Texinfo Style Guide
+
+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
+else is addressing OpenOCD developers.
+
+There are two key audiences for the User's Guide, both developer based.
+The primary audience is developers using OpenOCD as a tool in their
+work, or who may be starting to use it that way. A secondary audience
+includes developers who are supporting those users by packaging or
+customizing it for their hardware, installing it as part of some software
+distribution, or by evolving OpenOCD itself. There is some crossover
+between those audiences. We encourage contributions from users as the
+fundamental way to evolve and improve OpenOCD. In particular, creating
+a board or target specific configuration file is something that many
+users will end up doing at some point, and we like to see such files
+become part of the mainline release.
+
+General documentation rules to remember include:
+
+- Be concise and clear. It's work to remove those extra words and
+ sentences, but such "noise" doesn't help readers.
+- Make it easy to skim and browse. "Tell what you're going to say,
+ then say it". Help readers decide whether to dig in now, or
+ leave it for later.
+- Make sure the chapters flow well. Presentations should not jump
+ around, and should move easily from overview down to details.
+- Avoid using the passive voice.
+- Address the reader to clarify roles ("your config file", "the board you
+ are debugging", etc.); "the user" (etc) is artificial.
+- Use good English grammar and spelling. Remember also that English
+ will not be the first language for many readers. Avoid complex or
+ idiomatic usage that could create needless barriers.
+- Use examples to highlight fundamental ideas and common idioms.
+- Don't overuse list constructs. This is not a slide presentation;
+ prefer paragraphs.
+
+When presenting features and mechanisms of OpenOCD:
+
+- Explain key concepts before presenting commands using them.
+- Tie examples to common developer tasks.
+- When giving instructions, you can \@enumerate each step both
+ to clearly delineate the steps, and to highlight that this is
+ not explanatory text.
+- When you provide "how to use it" advice or tutorials, keep it
+ in separate sections from the reference material.
+- Good indexing is something of a black art. Use \@cindex for important
+ concepts, but don't overuse it. In particular, rely on the \@deffn
+ indexing, and use \@cindex primarily with significant blocks of text
+ such as \@subsection. The \@dfn of a key term may merit indexing.
+- Use \@xref (and \@anchor) with care. Hardcopy versions, from the PDF,
+ must make sense without clickable links (which don't work all that well
+ with Texinfo in any case). If you find you're using many links,
+ read that as a symptom that the presentation may be disjointed and
+ confusing.
+- Avoid font tricks like \@b, but use \@option, \@file, \@dfn, \@emph
+ and related mechanisms where appropriate.
+
+For technical reference material:
+
+- It's OK to start sections with explanations and end them with
+ detailed lists of the relevant commands.
+- Use the \@deffn style declarations to define all commands and drivers.
+ These will automatically appear in the relevant index, and those
+ declarations help promote consistent presentation and style.
+ - It's a "Command" if it can be used interactively.
+ - Else it's a "Config Command" if it must be used before the
+ configuration stage completes.
+ - For a "Driver", list its name.
+ - 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.
+ - Say what output it displays, and what value it returns to callers.
+ - Explain clearly what the command does. Sometimes you will find
+ that it can't be explained clearly. That usually means the command
+ is poorly designed; replace it with something better, if you can.
+ - Be complete: document all commands, except as part of a strategy
+ to phase something in or out.
+ - Be correct: review the documentation against the code, and
+ vice versa.
+- Alphabetize the \@defn declarations for all commands in each
+ section.
+- Keep the per-command documentation focussed on exactly what that
+ command does, not motivation, advice, suggestions, or big examples.
+ When commands deserve such expanded text, it belongs elsewhere.
+ Solutions might be using a \@section explaining a cluster of related
+ commands, or acting as a mini-tutorial.
+- Details for any given driver should be grouped together.
+
+The User's Guide is the first place most users will start reading,
+after they begin using OpenOCD. Make that investment of their time
+be as productive as possible. Needing to look at OpenOCD source code,
+to figure out how to use it is a bad sign, though it's OK to need to
+look at the User's guide to figure out what a config script is doing.
+
+ */
+/** @page stylelatex LaTeX Style Guide
+
+This page needs to provide style guidelines for using LaTeX, the
+typesetting language used by The References for OpenOCD Hardware.
+Likewise, the @ref primerlatex for using this guide needs to be completed.
+
+ */
+/** @page styleperl Perl Style Guide
+
+This page provides some style guidelines for using Perl, a scripting
+language used by several small tools in the tree:
+
+-# Ensure all Perl scripts use the proper suffix (@c .pl for scripts, and
+ @c .pm for modules)
+-# Pass files as script parameters or piped as input:
+ - Do NOT code paths to files in the tree, as this breaks out-of-tree builds.
+ - If you must, then you must also use an automake rule to create the script.
+-# use @c '#!/usr/bin/perl' as the first line of Perl scripts.
+-# always <code>use strict</code> and <code>use warnings</code>
+-# invoke scripts indirectly in Makefiles or other scripts:
+@code
+perl script.pl
+@endcode
+
+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>git add script.pl</code>"
+
+ */
+/** @page styleautotools Autotools Style Guide
+
+This page contains style guidelines for the OpenOCD autotools scripts.
+
+The following guidelines apply to the @c configure.ac file:
+- Better guidelines need to be developed, but until then...
+- Use good judgement.
+
+The following guidelines apply to @c Makefile.am files:
+-# When assigning variables with long lists of items:
+ -# Separate the values on each line to make the files "patch friendly":
+@code
+VAR = \
+ value1 \
+ value2 \
+ ...
+ value9 \
+ value10
+@endcode
+ */
+/** @file
+
+This file contains the @ref styleguide pages. The @ref styleguide pages
+include the following Style Guides for their respective code and
+documentation languages:
+
+- @ref styletcl
+- @ref stylec
+- @ref styledoxygen
+- @ref styletexinfo
+- @ref stylelatex
+- @ref styleperl
+- @ref styleautotools
*/
projects / fw / openocd / blobdiff