User:Oz Linden/Draft:DoxygenComments

The following is a set of proposed additions to our Coding Standard to specify the preferred use of Doxygen comments. At present, the standard just says to use them, but provides no guidance other than linking to the Doxygen manual, which is a long read and provides for many different styles and supports many more languages than we use. The goal of these proposed additions is to give the developer a quick and simple guide to the basics, which would be a lot better than we're doing now.

---

Common Guidelines

...

C++

...

Comments

We use the Doxygen system for generating documentation from header and source files. Doxygen supports a wide range of styles; this section provides recommendations for how it should be used in the Second Life Viewer project.

Doxygen Comment Style

Doxygen comments are distinguished from normal comments by an extra comment character at the beginning, and are associated with the adjacent code by their placement. Both C style comments and C++ single-line style comments are supported.

C++ single-line style comments

Doxygen interprets any C++ comment that has a '!' character at the beginning of a '//' comment, or an extra '*' character at the beginning of a '/* ... */' comment:

 //! A Doxygen single line comment

 /** A Doxygen single line comment */

C multiple-line style comments

 /// A Doxygen comment
 /// that extends over more than one line
 /// this form should be used whenever there is more than one line

note that triple slash does not work as a single line comment - it must have at least two lines

Comment Placement

Doxygen comments are, by default, associated with the code that immediately follows the comment:

 //! indicates whether or not the object currently allows any Foo actions.
 void isFooAllowed();

For some constructs it is more readable to place the comment after the code element it documents, which is accomplished by adding a '<' character after the Doxygen comment indicator. This may be used with either single or multi-line comments:

 void doFooAt( int offset ///< the offset into the Foo
              ,char* name ///< the name to look up for this Foo action
                          ///  in the FooMgr database.
             );

Placing the Doxygen comment after the element it documents in this way is preferred whenever the element is a member of a list, as in parameter declarations or enum values.

Class Documentation

A class declaration must include a detailed description comment preceding the class:

 /// FooFactory is a factory class that constructs instances of the
 /// subclasses of Foo based on information obtained from the
 /// foo-config file.
 class FooFactory
 {

The class comment is a good place to put general guidelines about how the methods in the class relate to one another.

Member Grouping

By default, Doxygen groups the members within a class based on heuristics that use the public/protected/private scope and the method signatures. For simple classes this usually works well, and may be used. When a class has many methods, it is usually better to explicitly control how they are grouped in the documentation, and to provide additional documentation at the group level. To explicitly control grouping, add the 'nosubgrouping' Doxygen command to the class comment:

 /// FooFactory is a factory class that constructs instances of the
 /// subclasses of Foo based on information obtained from the
 /// foo-config file.
 ///
 /// @nosubgrouping
 ///
 class FooFactory
 {

Each group is then formed of the following elements:

• An introducing Doxygen comment that supplies the group name using the 'name' Doxygen command,
• The detailed comment for the group,
• The Doxygen group start command '{',
• The declarations of the members in the group and accompanying documentation, and finally
• The Doxygen group end command '}'.

For example (preceeded here by a non-Doxygen comment with a line of '=' characters so that it reads better in the source file):

 // ================================================================================
 /// @name Searching
 ///
 /// The searching methods apply a compiled regular expression to a subject
 /// string.  All searching methods return a boolean result indicating whether
 /// or not some match was found in the subject.  To get information about
 /// the match, use the Results methods.
 ///
 ///@{
 ... the methods in the group ...
 ///@}

Member Function Documentation

Each member function should have:

• A brief single line description preceeding the member declaration
• Parameter descriptions following each parameter
• A more detailed description following the declaration, which should include a Doxygen 'returns' command if the method returns a value.

 /// Search a string for matches to this regular expression.
 bool Search( const char * subject ///< the string to be searched for a match
             ,int len = -1         ///< the length of the subject string
             ,int options = 0      ///< sum of any PCRE options flags
             );
 ///<  Apply the regular expression to the subject string.
 ///   Optional parameter len can be used to pass the subject's length to
 ///   Search(). If not specified (or less than 0), strlen() is used
 ///   internally to determine the length. Parameter options can contain
 ///   any combination of options; for options documentation, see 'man pcre'
 ///   @returns true if a match is found.

Usage Examples

Including examples in the documentation is strongly encouraged. To embed an example, use the Doxygen "@code ... @endcode" construct:

 ///<
 /// May only be called after a successful search
 /// and applies to the results of that call.
 /// @returns true if there was an ith match, false if not
 ///
 /// Example:@code
 /// RegEx matchBs("((B)B+)");
 /// UtlString getB;
 /// UtlString getBs;
 /// if (matchB.Search("xxaBBBBcyy"))
 /// {
 ///   matchB.MatchString(&getBs,0);
 ///   matchB.MatchString(&getB,2);
 /// }
 /// @endcode
 /// would set the UtlStrings
 ///  - getBs to "BBBB"
 ///  - getB  to "B"

Lists

Numbered and bulleted lists are supported in Doxygen comments using simple indentation conventions:

 ///< A numbered list is created using '#' characters:
 ///  # first numbered item
 ///  # second numbered item
 ///    # first item in nested numbered list (2.1)
 ///
 /// A bullet list uses '-' characters:
 ///  - first bullet
 ///  - second bullet
 ///    - nested bullet