Documenting Code

General notes & guidelines:

Doxygen is used to generate source code documentation
Most Doxygen comments should be in the header files (TBD)
Use mostly regular comments in implementations (i.e. source files). (TBD)
Use @command style, and not \command style Doxygen commands.

File documentation

Required Doxygen tags

@file
@brief
@author

Note: The @file tag is unnecessary when the documentation appears near the top of a file and is clearly not associated with any other code construct.

Class documentation

All classes should have a brief and detailed description that at least indicates what the class does. If the class has public or protected members, then those should be documented as follows:

Member Data

@brief

Methods (including stand-alone non-member functions)

For functions, please include the parameter descriptions before the further details about usage, limitations, etc. In general, the more than can be said about a function, the better.

@brief
@param
@returns
Detailed description

Program documentation

@brief
Detailed description including usage information

Other code constructs

@brief

Miscellaneous commands

A few other Doxygen commands are useful when documenting code and projects. The issues created with these commands are automatically collated into a summary pages dedicated to the issue type (i.e. bug, note, warning, or todo). This provides a convenient summary of all (known) bugs or a TODO list for a code or project.

@bug - allows a description of bugs in code constructs or programs
@note - is a general noting facility allowing construct-associated notes
@warning - is useful for alerting users or developers about construct-associated pitfalls or limitations
@todo - provides developers a way to note things left to do for a project or implementation

Examples of the documentation generated by the above commands:

Note: These commands are useful for creating notes on projects or constructs which are automatically summarized inline as well as in dedicated documentation pages.

Bug:: No known bugs.

Warning: Coding is inherently dangerous.

Todo:: Refactor away redundant code.

Formats for Code Comments

Doxygen interprets special commands and formatting in comments to generate documentation for your code and project. Doxygen also supports the Markdown markup language for formatting its generated documentation. The following sections are meant to be a summary with examples for some of the most useful commands and formats.

All of the documentation below is generated by the file: doc/Documentation.dox
Open it in your favorite editor to see how the documentation constructs below are created from comment formatting.

Markdown formats, and some html tags can be used inline with your comments to make your documentation pretty and more readable. Some useful examples follow.

Headers

The following examples show the syntax in a block quote, followed directly by how it would look in the generated documentation.

Different kinds of headers can be created like these...

  This is a first level header
  ===========================

This is a first level header

  This is a second level header
  ---------------------------

This is a second level header

  ###Third level header

Third level header

Italics and Bold

You can create italics by encasing in underscores like this (_italics_) and bold by encasing in asterics like this (**bold**) or by using html tags like this (<b>bold</b>).

Lists

A bulleted list can be created like this:

 * Element 1
 * Element 2
 * Element 3

Element 1
Element 2
Element 3

Lists of numbered items are created like this...

 1. Element 1
 2. Element 2
 3. Element 3

Element 1
Element 2
Element 3

Links

Embed links in your documentation like this:

[IRPMI](http://irweb/redmine "This is the mouseover text.")

IRPMI

Blockquotes and Code Sections

Blockquotes can be made by using the >, like this:

 > Use blockquotes especially when documenting user
 > commands and stuff like that.
 > New lines are ignored internally but can be done\n
 > by forcing with "\n"

Use blockquotes especially when documenting user commands and stuff like that. New lines are ignored internally but can be done
by forcing with "\n"

Blockquotes can also be created with the <blockquote> html tag:

  <blockquote>
  This text will be block-quoted.\n
  The blockquote continues on the next line.
  </blockquote>

This text will be block-quoted.
The blockquote continues on the next line.

Note the explicit forcing of a newline with "\n".

Code snippets can also be encapsulated as such: @code

int test_code_section;
char disco_inferno;
@endcode

*  int test_code_section;
*  char disco_inferno;
*  

Tables

Tables are simple to create in doxygen with the Markdown syntax. Here's the syntax for the following example table:

   | Type  |     Description    |      Usage     |    Value        |
   | ----: | :----------------: | :------------: | :-------------- |
   |  0    | simple flag        | -t             | .true.          |
   |  1    | argument optional  | -t or -t [arg] | .true. or [arg] |
   |  2    | argument required  | -t <arg>       | <arg>           |
   |  3    | required w/arg     | -t <arg>       | <arg>           |

creates the following table:

Type	Description	Usage	Value
0	simple flag	-t	.true.
1	argument optional	-t or -t [arg]	.true. or [arg]
2	argument required	-t <arg>	<arg>
3	required w/arg	-t <arg>	<arg>

Latex

Latex can be directly embedded into your comments by delineating the latex code in \f$'s.

\f$\bar{\mu} = \frac{1}{N}\Sigma_{n=1}{N}\frac{x_n}{n!}\f$