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 Doxygen Primer.

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.

1. use /// to for one-line documentation of instances.
2. for documentation requiring multiple lines, use a "block" style:

   /**
    * @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.
    */
   

   1. The block should start on the line following the opening /**.
   2. The end of the block, *‍/, should also be on its own line.
   3. Every line in the block should have a '*' in-line with its start:
      • A leading space is required to align the '*' with the /** 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.
   4. Only single spaces should be used; do not add mid-line indentation.
3. If the total line length will be less than 72-80 columns, then
   • The /**< form can be used on the same line.
   • This style should be used sparingly; the best use is for fields:

     int field; /**< field description */ 

Doxygen Style Guide

The following guidelines apply to all Doxygen comment blocks:

1. Use the '@cmd' form for all doxygen commands (do not use '\cmd').
2. Use symbol names such that Doxygen automatically creates links:
   1. function_name() can be used to reference functions (e.g. flash_set_dirty()).
   2. struct_name::member_name should be used to reference structure fields in the documentation (e.g. flash_driver::name).
   3. URLS get converted to markup automatically, without any extra effort.
   4. new pages can be linked into the hierarchy by using the @subpage command somewhere the page(s) under which they should be linked:
   5. use @ref in other contexts to create links to pages and sections.
3. Use good Doxygen mark-up:
   1. '@a' (italics) should be used to reference parameters (e.g. foo).
   2. '@b' (bold) should be used to emphasizing single words.
   3. '@c' (monospace) should be used with file names and code symbols, so they appear visually distinct from surrounding text.
   4. To mark-up multiple words, the HTML alternatives must be used.
4. Two spaces should be used when nesting lists; do not use '\t' in lists.
5. Code examples provided in documentation must conform to the Style Guide.

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:

1. Text files must contain Doxygen at least one comment block:
   1. Documentation should begin in the first column (except for nested lists).
   2. Do NOT use the '*' convention that must be used in the source code.
2. Each file should contain at least one @page block.
   1. Each new page should be listed as a @subpage in the @page block of the page that should serve as its parent.
   2. Large pages should be structure in parts using meaningful @section and @subsection commands.
3. Include a @file block at the end of each Doxygen .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 technical writers; typically, a list of the pages that it contains.
   • For example, the Style Guides exists in doc/manual/style.txt, which contains a reference back to itself.
4. The @file and @page commands should begin on the same line as the start of the Doxygen comment:

   /** @page pagename Page Title
   
   Documentation for the page.
   
    */
   /** @file
   
   This file contains the @ref pagename page.
   
    */
   

For an example, the Doxygen source for this Style Guide can be found in doc/manual/style.txt, alongside other parts of The Manual.