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

WolfPup Lowenhar wolfpup67 at earthlink.net
Fri Sep 16 06:34:42 PDT 2011


Oz,

The in code comments is something that has been needed for YEARS and there
is virtually NO documentation of how the different functions do what they do
and I personally have been trying to put in documentation on any sections of
code I submit. To get the code fully documented will more than likely take
at least a year but this is a good start to getting that done as far as I'm
concerned.

 

From: opensource-dev-bounces at lists.secondlife.com
[mailto:opensource-dev-bounces at lists.secondlife.com] On Behalf Of Oz Linden
(Scott Lawrence)
Sent: Friday, September 16, 2011 9:25 AM
To: opensource-dev
Subject: [opensource-dev] Draft addition to coding standard for Doxygen
usage

 

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

 

  _____  

No virus found in this message.
Checked by AVG - www.avg.com
Version: 2012.0.1808 / Virus Database: 2085/4500 - Release Date: 09/16/11

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


More information about the opensource-dev mailing list