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-boun...@lists.secondlife.com [mailto:opensource-dev-boun...@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
_______________________________________________ Policies and (un)subscribe information available here: http://wiki.secondlife.com/wiki/OpenSource-Dev Please read the policies before posting to keep unmoderated posting privileges
