debuggers: import openocd-0.7.0
Initial check-in of openocd-0.7.0 as it can be downloaded from http://sourceforge.net/projects/openocd/files/openocd/0.7.0/ Any modifications will follow. Change-Id: I6949beaefd589e046395ea0cb80f4e1ab1654d55
This commit is contained in:
Lars Rademacher
403
debuggers/openocd/doc/manual/style.txt
Normal file
403
debuggers/openocd/doc/manual/style.txt
Normal file
@ -0,0 +1,403 @@
|
||||
/** @page styleguide Style Guides
|
||||
|
||||
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.
|
||||
|
||||
Some of these rules may be ignored in the spirit of these stated goals;
|
||||
however, such exceptions should be fairly rare.
|
||||
|
||||
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.
|
||||
- displayed TAB width is 4 characters.
|
||||
- use Unix line endings ('\\n'); do NOT use DOS endings ('\\r\\n')
|
||||
- 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 (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:
|
||||
|
||||
- long lines frequently indicate other style problems:
|
||||
- insufficient use of static functions, macros, or temporary variables
|
||||
- poor flow-control structure; "inverted" logical tests
|
||||
- a few lines may be wider than this limit (typically format strings), but:
|
||||
- all C compilers will concatenate series of string constants.
|
||||
- all long string constants should be split across multiple lines.
|
||||
|
||||
@section stylenames Naming Rules
|
||||
|
||||
- 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.
|
||||
- @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 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 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
|
||||
|
||||
- static inline functions should be prefered over macros:
|
||||
@code
|
||||
/** do NOT define macro-like functions like this... */
|
||||
#define CUBE(x) ((x) * (x) * (x))
|
||||
/** instead, define the same expression using a C99 inline function */
|
||||
static inline int cube(int x) { return x * x * x; }
|
||||
@endcode
|
||||
- Functions should be declared static unless required by other modules
|
||||
- define static functions before first usage to avoid forward declarations.
|
||||
- Functions should have no space between its name and its parameter list:
|
||||
@code
|
||||
int f(int x1, int x2)
|
||||
{
|
||||
...
|
||||
int y = f(x1, x2 - x1);
|
||||
...
|
||||
}
|
||||
@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
|
||||
|
||||
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 of instances.
|
||||
-# for documentation requiring multiple lines, use a "block" style:
|
||||
@verbatim
|
||||
/**
|
||||
* @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
|
||||
-# 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
|
||||
|
||||
@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
|
||||
|
||||
*/
|
||||
Reference in New Issue
Block a user