[opensource-dev] Draft addition to coding standard for Doxygen usage

Oz Linden (Scott Lawrence) oz at lindenlab.com
Fri Sep 16 06:25:04 PDT 2011


Our current coding standard says:

    Prefer the use of doxygen compatible comment markup. (See Using
    Doxygen.)

and "Using Doxygen" has installation instructions and then points to the 
Doxygen manual.

I've gotten the viewer build modified (locally... not yet checked in) so 
that generating the Doxygen documentation is easy (with the goal of 
getting it posted and automatically updated on the net soon).

In fact hardly any of our viewer code currently has doxygen-compatible 
comments, and too much of it lacks any descriptive comments at all, even 
in the .h files.

In hopes that making it easier will encourage everyone to do more 
documenting, I've drafted some additions to our Coding Standard 
<https://wiki.secondlife.com/wiki/Coding_Standard> to provide simple 
tutorial on the basics of Doxygen comments and to recommend a uniform 
style (other styles will still work, and I'd be delighted to see any 
usage in any style that works).  My draft is posted at

    https://wiki.secondlife.com/wiki/User:Oz_Linden/Draft:DoxygenComments

and included below...


------------------------------------------------------------------------


        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


-------------- next part --------------
An HTML attachment was scrubbed...
URL: http://lists.secondlife.com/pipermail/opensource-dev/attachments/20110916/708f2b17/attachment-0001.htm 


More information about the opensource-dev mailing list