How to Write C++ Source Code Documentation for Autodoc

Content

Basic Rules
What can be documented
Layout
Tags
Common Tags
Tags for Classes
Tags for Functions
Tags for Variables
Global Tags
A Typical Documentation

Scope

This is a description of how to write documentation within C++ code such it can be automatically parsed by the source code documentation tool Autodoc.

Basic Rules

• There are two possibilities to put documentation in a C++ file:
  Multi line documentation starts with /** and ends with */ so it looks like this:

  /** Some text
      .................
      .................
  */

  Single line or “inline” documentation starts with /// and ends with the line, so it looks like this:

  ///  Some text .......

  A “documentation paragraph” we call any of the two just described documentation blocks.

• The language of documentation is English.
• So far, only header files are parsed by Autodoc.
• For most typical uses, the documentation style is compatible to Javadoc.
  Only you can not use the leftside *-bar as it is used in Java:

  /** Text
    * ...
    */

  will not work.
• Attention: The first "/**"-comment in each file is ignored.
  That is because Autodoc is usually used to parse files with license-, CVS- or other specific headers which usually start with "/**" as well.
  Should you have a file without such a header, you need to insert a dummy comment.

What can be Documented

Documentable code entities in C++ are:

• classes (including structs and unions)
• enums
• functions / methods
• variables (including constants)
• enum values
• #define-s
• #define-d macros.

All documentation belongs to the next following documentable code entity. If there are more than one documentation paragraph following each other, the last one wins.
Also be aware, that the first "/**"-comment in each file is interpreted as special file header and not recognized by Autodoc.

Layout

If there is no @-tag at the beginning of a documentation paragraph, the first part of it is interpreted like @short , if it is not more than two lines and followed by an empty line.
After that empty line, or if it is more than two lines, text without an @-tag it is interpreted like @descr .

The following layout is required:

• Leading '*'s or '#'s in each documentation line must not be used!
• All @-tags have to be the first non whitespace in their line, except of the /** start of a documentation paragraph.

The following layout is recommended:

• Use multi line documentation (/**...*/).
• Start the documentation in the same line as the /** .
• The begin and end sign ( /** and */ ) of a multi line documentation start in the same column as the documented code entity.
• Each line and each tag start 4 columns to the right of the begin and end sign (“/** and */”).

HTML tags can be used or not.
Default is no HTML. ( Because this makes writing documentation easier and faster. If documentation is easier its probability to exist increases. ) In this case, all line breaks and all indentations will be preserved in the generated documentation. All other things like “<BR>” will appear without modification, still in the generated documentation.
If HTML shall be used (for publicly used libraries a more sophisticated layout may be desired), this can be done by the tags @HTML and @NOHTML . They switch the recognising of HTML on or off for the rest of the file, or until the next such tag.


Tags

Legend

A '|' within a tag

means that the tag can be abbreviated at this position

Words in the same line as the @-tag

are parameters to it.

<ABC>

a parameter

"by"

Text within "" is to be used literally.

[...]

Parameters within [] is optional.

NOTEXT

There can't be any additional text to this tag.

All tags with parameters can't have any more text in the same line after the parameters. Parameters not enclosed in square brackets [] are required and must be specified.

tag  required-parameter [optional-parameter]

Common Tags

@ATT|ENTION

Is to be used, if intuitive use of a function may be wrong. Or if it is to be used only in very specific circumstances.

@author <A.Name>

Creator of the code. This is to be changed to the (last) person, who did changes and therefore is responsible for the present code. If the person, who did the last change, is not responsible for the code (may be, because the author was on vacation), the @change tag is to be used. This tag can be used hierarchically: If there is an author tag in the class documentation, not every member needs an own one If there is an author tag in a member too, it belongs to that member only. The same for enums and their values.
NOTEXT.

@change <dd.mm.yyyy> "by" <WhoDidTheChange>

There has to be a new @change tag for each change, newest at top.

@deprecated

Marks an code entity as existing only for backwards compatibility.
NOTEXT

@descr

The main text describing the documented entity.
The tag can be omitted before this text (see A Typical Documentation ).

@docdate <dd.mm.yyyy>

Date of documentation. The last date, when this documentation was changed.
NOTEXT.

@empty

Special tag for tested documentation. It means, here, no documentation is intended.
NOTEXT.


@internal

Typical for not exported or otherwise hidden functions. The documentation for this code entity can be filtered out of the created documentation.
NOTEXT.

@key <KeyWord>

This tag provides the possibility to search in the created documentation or to filter it, by the given key.
One tag for each key.
Use with care. Too many keys don't support clarity. Maybe, possible keywords in a project should be defined by the team.
NOTEXT.

@see|also >>WhatToSee<<

This points to a related documented code entity.
NOTEXT.

@short

A short text (typical just one line) describing the documented entity. For instance, this text may be used in indices as a short description.
The tag can be omitted before this text (see A Typical Documentation ).

@todo

Tasks which are still open with a code entity.

Tags for Classes

@base >>BaseClass<<

Comment to a base class.
Use this only, if there are comments. Simple listing of base classes is done automaticly.

@collab|orator >>TheCollaborator<<

>This is to be used in the sense of CRC Cards .
One tag for each collaborator.

@derive

If the class is designed for derivation, here can be described, how to do this: Which methods should be rewritten, which should not etc.

@instance <ObjectName>

Describes a (or the one) specific instance of this class.
One tag for each instance.

@interface

This tag says, this class is to be used only as an interface and implementation is in derived classes.
NOTEXT.

@invariant

Can be used for formal invariants of this class. Recommended for publicly used library classes/interfaces.

@resp|onsibility

This is to be used in the sense of CRC Cards .
One tag for each responsibility.

@tpl|param <TplParamName>

Only for templates. Describes a template parameter: meaning, requirements, restrictions.
One tag for each template parameter.


Tags for Functions

@exception >>ExceptionType<<

Describes one exception.
One tag for each exception.
Use this only, if there are comments. Simple listing of exceptions is done automaticly.

@invariant

Can be used for formal invariants of this function. 

@onerror

Handling of error conditions. Can be used, if there is no exception specification.

@param <ParameterName> [ "["<ValidRange> "]" ]

Describes one function parameter.
The range is optional, but the '[' and ']' must be literally there, if a range is given. (They are not meant as an "optional parameter" sign here).
One tag for each parameter.
Use this only, if there are comments. Simple listing of parameters is done automaticly.

@postcond

Can be used for formal postconditions of this function. Recommended for publicly used library functions.

@precond

Can be used for formal preconditions of this function. Recommended for publicly used library functions.

@return

Describes the return values of the function.

@tpl|param <TplParameterName>

Only for templates. Describes a template parameter: meaning, requirements, restrictions.
One tag for each template parameter.

Tags for Variables

@dyn

This marks a pointer variable as owner of a heap object. If used consequently, this is always makes clear, if a pointer should be deleted or is only referencing. This tag must not be used for refcounted objects. If it exists, it always means: Use delete on this variable, or pass it on to somebody, who deletes it reliably.


@life|cycle

Describes, when a variable is created and destroyed.

@multi|plicity <Range>

Range can be something like “1+”, “0+”, “2..5”, “Strings up to 255 characters”.

Global Tags

@HTML

For the rest of the source code file (or till the next @NOHTML ), HTML-tags in documentation will be recognised as such.

@NOHTML

For the rest of the source code file (or till the next @HTML ), HTML-tags in documentation will be ignored and handled like normal text, ie. not translated.

A Typical Documentation

/** Short comment: This is for .... .

    After an empty line, here comes the main description of the code
    entity. Here can be a longer text, examples,
    philosophical considerations and special solution descriptions.
    After this text, only @-tags are allowed. Each following text belongs
    to its prefacing @-tag.

    @param integer1 [0 .. 255]
    Describe parameter integer1.

    @param str2
    Describe the parameter str2.

    @return true, if everything is ok. Else false.
*/
bool   funct_00( int integer1, const char * str2 );