[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