Doc/examples: clarify usage messages
[openocd.git] / doc / manual / style.txt
1 /** @page styleguide Style Guides
2
3 The goals for each of these guides are:
4 - to produce correct code that appears clean, consistent, and readable,
5 - to allow developers to create patches that conform to a standard, and
6 - to eliminate these issues as points of future contention.
7
8 Some of these rules may be ignored in the spirit of these stated goals;
9 however, such exceptions should be fairly rare.
10
11 The following style guides describe a formatting, naming, and other
12 conventions that should be followed when writing or changing the OpenOCD
13 code:
14
15 - @subpage styletcl
16 - @subpage stylec
17 - @subpage styleperl
18 - @subpage styleautotools
19
20 In addition, the following style guides provide information for
21 providing documentation, either as part of the C code or stand-alone.
22
23 - @subpage styledoxygen
24 - @subpage styletexinfo
25 - @subpage stylelatex
26
27 Feedback would be welcome to improve the OpenOCD guidelines.
28
29  */
30 /** @page styletcl TCL Style Guide
31
32 OpenOCD needs to expand its Jim/TCL Style Guide.
33
34 Many of the guidelines listed on the @ref stylec page should apply to
35 OpenOCD's Jim/TCL code as well.
36
37  */
38 /** @page stylec C Style Guide
39
40 This page contains guidelines for writing new C source code for the
41 OpenOCD project.
42
43 @section styleformat Formatting Guide
44
45 - remove any trailing white space at the end of lines.
46 - use TAB characters for indentation; do NOT use spaces.
47 - displayed TAB width is 4 characters.
48 - use Unix line endings ('\\n'); do NOT use DOS endings ('\\r\\n')
49 - limit adjacent empty lines to at most two (2).
50 - remove any trailing empty lines at the end of source files
51 - do not "comment out" code from the tree; instead, one should either:
52   -# remove it entirely (git can retrieve the old version), or
53   -# use an @c \#if/\#endif block.
54
55 Finally, try to avoid lines of code that are longer than than 72-80 columns:
56
57 - long lines frequently indicate other style problems:
58   - insufficient use of static functions, macros, or temporary variables
59   - poor flow-control structure; "inverted" logical tests
60 - a few lines may be wider than this limit (typically format strings), but:
61   - all C compilers will concatenate series of string constants.
62   - all long string constants should be split across multiple lines.
63
64 @section stylenames Naming Rules
65
66 - most identifiers must use lower-case letters (and digits) only.
67   - macros must use upper-case letters (and digits) only.
68   - OpenOCD identifiers should NEVER use @c MixedCaps.
69 - @c typedef names must end with the '_t' suffix.
70   - This should be reserved for types that should be passed by value.
71   - Do @b not mix the typedef keyword with @c struct.
72 - use underline characters between consecutive words in identifiers
73   (e.g. @c more_than_one_word).
74
75 @section stylec99 C99 Rules
76
77 - inline functions
78 - @c // comments -- in new code, prefer these for single-line comments
79 - trailing comma allowed in enum declarations
80 - designated initializers (@{ .field = value @})
81 - variables declarations should occur at the point of first use
82 - new block scopes for selection and iteration statements
83 - use malloc() to create dynamic arrays. Do @b not use @c alloca
84 or variable length arrays on the stack. non-MMU hosts(uClinux) and
85 pthreads require modest and predictable stack usage.
86
87 @section styletypes Type Guidelines
88 - use native types (@c int or @c unsigned) if the type is not important
89   - if size matters, use the types from \<stdint.h\> or \<inttypes.h\>:
90     - @c int8_t, @c int16_t, @c int32_t, or @c int64_t: signed types of specified size
91     - @c uint8_t, @c uint16_t, @c uint32_t, or @c uint64_t: unsigned types of specified size
92   - do @b NOT redefine @c uN types from "types.h"
93
94 @section stylefunc Functions
95
96 - static inline functions should be prefered over macros:
97 @code
98 /** do NOT define macro-like functions like this... */
99 #define CUBE(x) ((x) * (x) * (x))
100 /** instead, define the same expression using a C99 inline function */
101 static inline int cube(int x) { return x * x * x; }
102 @endcode
103 - Functions should be declared static unless required by other modules
104   - define static functions before first usage to avoid forward declarations.
105 - Functions should have no space between its name and its parameter list:
106 @code
107 int f(int x1, int x2)
108 {
109         ...
110         int y = f(x1, x2 - x1);
111         ...
112 }
113 @endcode
114 - Separate assignment and logical test statements.  In other words, you
115 should write statements like the following:
116 @code
117 // separate statements should be preferred
118 result = foo();
119 if (ERROR_OK != result)
120         ...
121 @endcode
122 More directly, do @b not combine these kinds of statements:
123 @code
124 // Combined statements should be avoided
125 if (ERROR_OK != (result = foo()))
126         return result;
127 @endcode
128
129  */
130 /** @page styledoxygen Doxygen Style Guide
131
132 The following sections provide guidelines for OpenOCD developers
133 who wish to write Doxygen comments in the code or this manual.
134 For an introduction to Doxygen documentation,
135 see the @ref primerdoxygen.
136
137 @section styledoxyblocks Doxygen Block Selection
138
139 Several different types of Doxygen comments can be used; often,
140 one style will be the most appropriate for a specific context.
141 The following guidelines provide developers with heuristics for
142 selecting an appropriate form and writing consistent documentation
143 comments.
144
145 -# use @c /// to for one-line documentation of instances.
146 -# for documentation requiring multiple lines, use a "block" style:
147 @verbatim
148 /**
149  * @brief First sentence is short description.  Remaining text becomes
150  * the full description block, where "empty" lines start new paragraphs.
151  *
152  * One can make text appear in @a italics, @b bold, @c monospace, or
153  * in blocks such as the one in which this example appears in the Style
154  * Guide.  See the Doxygen Manual for the full list of commands.
155  *
156  * @param foo For a function, describe the parameters (e.g. @a foo).
157  * @returns The value(s) returned, or possible error conditions.
158  */
159 @endverbatim
160   -# The block should start on the line following the opening @c /**.
161   -# The end of the block, \f$*/\f$, should also be on its own line.
162   -# Every line in the block should have a @c '*' in-line with its start:
163     - A leading space is required to align the @c '*' with the @c /** line.
164     - A single "empty" line should separate the function documentation
165       from the block of parameter and return value descriptions.
166     - Except to separate paragraphs of documentation, other extra
167       "empty" lines should be removed from the block.
168   -# Only single spaces should be used; do @b not add mid-line indentation.
169 -# If the total line length will be less than 72-80 columns, then
170   - The @c /**< form can be used on the same line.
171   - This style should be used sparingly; the best use is for fields:
172     @code int field; /**< field description */ @endcode
173
174 @section styledoxyall Doxygen Style Guide
175
176 The following guidelines apply to all Doxygen comment blocks:
177
178 -# Use the @c '\@cmd' form for all doxygen commands (do @b not use @c '\\cmd').
179 -# Use symbol names such that Doxygen automatically creates links:
180   -# @c function_name() can be used to reference functions
181     (e.g. flash_set_dirty()).
182   -# @c struct_name::member_name should be used to reference structure
183     fields in the documentation (e.g. @c flash_driver::name).
184   -# URLS get converted to markup automatically, without any extra effort.
185   -# new pages can be linked into the heirarchy by using the @c \@subpage
186     command somewhere the page(s) under which they should be linked:
187   -# use @c \@ref in other contexts to create links to pages and sections.
188 -# Use good Doxygen mark-up:
189   -# '\@a' (italics) should be used to reference parameters (e.g. <i>foo</i>).
190   -# '\@b' (bold) should be used to emphasizing <b>single</b> words.
191   -# '\@c' (monospace) should be used with <code>file names</code> and
192   <code>code symbols</code>, so they appear visually distinct from
193   surrounding text.
194   -# To mark-up multiple words, the HTML alternatives must be used.
195 -# Two spaces should be used when nesting lists; do @b not use '\\t' in lists.
196 -# Code examples provided in documentation must conform to the Style Guide.
197
198 @section styledoxytext Doxygen Text Inputs
199
200 In addition to the guidelines in the preceding sections, the following
201 additional style guidelines should be considered when writing
202 documentation as part of standalone text files:
203
204 -# Text files must contain Doxygen at least one comment block:
205   -# Documentation should begin in the first column (except for nested lists).
206   -# Do NOT use the @c '*' convention that must be used in the source code.
207 -# Each file should contain at least one @c \@page block.
208   -# Each new page should be listed as a \@subpage in the \@page block
209   of the page that should serve as its parent.
210   -# Large pages should be structure in parts using meaningful \@section
211   and \@subsection commands.
212 -# Include a @c \@file block at the end of each Doxygen @c .txt file to
213   document its contents:
214   - Doxygen creates such pages for files automatically, but no content
215     will appear on them for those that only contain manual pages.
216   - The \@file block should provide useful meta-documentation to assist
217     techincal writers; typically, a list of the pages that it contains.
218   - For example, the @ref styleguide exists in @c doc/manual/style.txt,
219     which contains a reference back to itself.
220 -# The \@file and \@page commands should begin on the same line as
221    the start of the Doxygen comment:
222 @verbatim
223 /** @page pagename Page Title
224
225 Documentation for the page.
226
227  */
228 /** @file
229
230 This file contains the @ref pagename page.
231
232  */
233 @endverbatim
234
235 For an example, the Doxygen source for this Style Guide can be found in
236 @c doc/manual/style.txt, alongside other parts of The Manual.
237
238  */
239 /** @page styletexinfo Texinfo Style Guide
240
241 The User's Guide is there to provide two basic kinds of information.  It
242 is a guide for how and why to use each feature or mechanism of OpenOCD.
243 It is also the reference manual for all commands and options involved
244 in using them, including interface, flash, target, and other drivers.
245 At this time, it is the only user-targetted documentation; everything
246 else is addressing OpenOCD developers.
247
248 There are two key audiences for the User's Guide, both developer based.
249 The primary audience is developers using OpenOCD as a tool in their
250 work, or who may be starting to use it that way.  A secondary audience
251 includes developers who are supporting those users by packaging or
252 customizing it for their hardware, installing it as part of some software
253 distribution, or by evolving OpenOCD itself.  There is some crossover
254 between those audiences.  We encourage contributions from users as the
255 fundamental way to evolve and improve OpenOCD.  In particular, creating
256 a board or target specific configuration file is something that many
257 users will end up doing at some point, and we like to see such files
258 become part of the mainline release.
259
260 General documentation rules to remember include:
261
262 - Be concise and clear.  It's work to remove those extra words and
263   sentences, but such "noise" doesn't help readers.
264 - Make it easy to skim and browse.  "Tell what you're going to say,
265   then say it".  Help readers decide whether to dig in now, or
266   leave it for later.
267 - Make sure the chapters flow well.  Presentations should not jump
268   around, and should move easily from overview down to details.
269 - Avoid using the passive voice.
270 - Address the reader to clarify roles ("your config file", "the board you
271   are debugging", etc.); "the user" (etc) is artificial.
272 - Use good English grammar and spelling.  Remember also that English
273   will not be the first language for many readers.  Avoid complex or
274   idiomatic usage that could create needless barriers.
275 - Use examples to highlight fundamental ideas and common idioms.
276 - Don't overuse list constructs.  This is not a slide presentation;
277   prefer paragraphs.
278
279 When presenting features and mechanisms of OpenOCD:
280
281 - Explain key concepts before presenting commands using them.
282 - Tie examples to common developer tasks.
283 - When giving instructions, you can \@enumerate each step both
284   to clearly delineate the steps, and to highlight that this is
285   not explanatory text.
286 - When you provide "how to use it" advice or tutorials, keep it
287   in separate sections from the reference material.
288 - Good indexing is something of a black art.  Use \@cindex for important
289   concepts, but don't overuse it.  In particular, rely on the \@deffn
290   indexing, and use \@cindex primarily with significant blocks of text
291   such as \@subsection.  The \@dfn of a key term may merit indexing.
292 - Use \@xref (and \@anchor) with care.  Hardcopy versions, from the PDF,
293   must make sense without clickable links (which don't work all that well
294   with Texinfo in any case).  If you find you're using many links,
295   read that as a symptom that the presentation may be disjointed and
296   confusing.
297 - Avoid font tricks like \@b, but use \@option, \@file, \@dfn, \@emph
298   and related mechanisms where appropriate.
299
300 For technical reference material:
301
302 - It's OK to start sections with explanations and end them with
303   detailed lists of the relevant commands.
304 - Use the \@deffn style declarations to define all commands and drivers.
305   These will automatically appear in the relevant index, and those
306   declarations help promote consistent presentation and style.
307    - It's a "Command" if it can be used interactively.
308    - Else it's a "Config Command" if it must be used before the
309      configuration stage completes.
310    - For a "Driver", list its name.
311    - Use EBNF style regular expressions to define parameters:
312      brackets around zero-or-one choices, parentheses around
313      exactly-one choices.
314    - Use \@option, \@file, \@var and other mechanisms where appropriate.
315    - Say what output it displays, and what value it returns to callers.
316    - Explain clearly what the command does.  Sometimes you will find
317      that it can't be explained clearly.  That usually means the command
318      is poorly designed; replace it with something better, if you can.
319    - Be complete:  document all commands, except as part of a strategy
320      to phase something in or out.
321    - Be correct:  review the documentation against the code, and
322      vice versa.
323 - Alphabetize the \@defn declarations for all commands in each
324   section.
325 - Keep the per-command documentation focussed on exactly what that
326   command does, not motivation, advice, suggestions, or big examples.
327   When commands deserve such expanded text, it belongs elsewhere.
328   Solutions might be using a \@section explaining a cluster of related
329   commands, or acting as a mini-tutorial.
330 - Details for any given driver should be grouped together.
331
332 The User's Guide is the first place most users will start reading,
333 after they begin using OpenOCD.  Make that investment of their time
334 be as productive as possible.  Needing to look at OpenOCD source code,
335 to figure out how to use it is a bad sign, though it's OK to need to
336 look at the User's guide to figure out what a config script is doing.
337
338  */
339 /** @page stylelatex LaTeX Style Guide
340
341 This page needs to provide style guidelines for using LaTeX, the
342 typesetting language used by The References for OpenOCD Hardware.
343 Likewise, the @ref primerlatex for using this guide needs to be completed.
344
345  */
346 /** @page styleperl Perl Style Guide
347
348 This page provides some style guidelines for using Perl, a scripting
349 language used by several small tools in the tree:
350
351 -# Ensure all Perl scripts use the proper suffix (@c .pl for scripts, and
352    @c .pm for modules)
353 -# Pass files as script parameters or piped as input:
354   - Do NOT code paths to files in the tree, as this breaks out-of-tree builds.
355   - If you must, then you must also use an automake rule to create the script.
356 -# use @c '#!/usr/bin/perl' as the first line of Perl scripts.
357 -# always <code>use strict</code> and <code>use warnings</code>
358 -# invoke scripts indirectly in Makefiles or other scripts:
359 @code
360 perl script.pl
361 @endcode
362
363 Maintainers must also be sure to follow additional guidelines:
364 -# Ensure that Perl scripts are committed as executables:
365     Use "<code>chmod +x script.pl</code>"
366     @a before using "<code>git add script.pl</code>"
367
368  */
369 /** @page styleautotools Autotools Style Guide
370
371 This page contains style guidelines for the OpenOCD autotools scripts.
372
373 The following guidelines apply to the @c configure.in file:
374 - Better guidelines need to be developed, but until then...
375 - Use good judgement.
376
377 The following guidelines apply to @c Makefile.am files:
378 -# When assigning variables with long lists of items:
379   -# Separate the values on each line to make the files "patch friendly":
380 @code
381 VAR = \
382         value1 \
383         value2 \
384         ...
385         value9 \
386         value10
387 @endcode
388  */
389 /** @file
390
391 This file contains the @ref styleguide pages.  The @ref styleguide pages
392 include the following Style Guides for their respective code and
393 documentation languages:
394
395 - @ref styletcl
396 - @ref stylec
397 - @ref styledoxygen
398 - @ref styletexinfo
399 - @ref stylelatex
400 - @ref styleperl
401 - @ref styleautotools
402
403  */