User Tools

Site Tools


efficient_doxygen_comments

Differences

This shows you the differences between two versions of the page.

Link to this comparison view

Both sides previous revision Previous revision
efficient_doxygen_comments [2015/02/12 10:22]
Jon A. Cruz [Breakdown]
efficient_doxygen_comments [2015/08/12 18:25] (current)
Jon A. Cruz [Breakdown]
Line 38: Line 38:
   * Inline comments must be single-line (''​%%//​%%''​) format.   * Inline comments must be single-line (''​%%//​%%''​) format.
   * Multi-line comments should follow the JavaDoc (''​%%/​**%%''​ ''​%%*/​%%''​) format.   * Multi-line comments should follow the JavaDoc (''​%%/​**%%''​ ''​%%*/​%%''​) format.
-  * Comments should start with a brief summary of a single sentence terminated with a period (''​%%.%%''​).+  ​* Copyright and other blocks must not accidentally start with a line of asterisks such as one beginning "''​%%/​*****...%%''"​. 
 +  ​* Comments should start with a brief summary of a single sentence terminated with a period (''​%%.%%''​). Ending with a period is actually required for proper Doxygen functionality.
   * Explicit use of ''​%%@brief%%''​ should be avoided.   * Explicit use of ''​%%@brief%%''​ should be avoided.
       * Configuration '​Doxygen'​ files should enable ''​%%JAVADOC_AUTOBRIEF%%''​.       * Configuration '​Doxygen'​ files should enable ''​%%JAVADOC_AUTOBRIEF%%''​.
Line 45: Line 46:
     * If a comment is not near the item being documented, a developer can easily miss getting it updated when they touch the code.     * If a comment is not near the item being documented, a developer can easily miss getting it updated when they touch the code.
   * For compact declarations such as members of an ''​%%enum%%''​ or ''​%%struct%%'',​ a comment can immediately follow the item being documented if it has a less-than character at the begining (''​%%/​**<​%%''​ ''​%%*/​%%''​).   * For compact declarations such as members of an ''​%%enum%%''​ or ''​%%struct%%'',​ a comment can immediately follow the item being documented if it has a less-than character at the begining (''​%%/​**<​%%''​ ''​%%*/​%%''​).
-  * Avoid using the doxygen tags delcaring ​what is being documented (''​%%@fn%%'',​ ''​%%@var%%'',​ ''​%%@property%%'',​ ''​%%@typedef%%'',​ etc.)+  * Avoid using the doxygen tags declaring ​what is being documented (''​%%@struct%%'', ​''​%%@fn%%'',​ ''​%%@var%%'',​ ''​%%@property%%'',​ ''​%%@typedef%%'',​ etc.)
     * Doxygen itself even [[http://​www.stack.nl/​~dimitri/​doxygen/​manual/​commands.html#​cmdfn|warns]] "Do not use this command if it is not absolutely needed, since it will lead to duplication of information and thus to errors."​     * Doxygen itself even [[http://​www.stack.nl/​~dimitri/​doxygen/​manual/​commands.html#​cmdfn|warns]] "Do not use this command if it is not absolutely needed, since it will lead to duplication of information and thus to errors."​
-  * ''​%%@return%%''​ tags are not needed for ''​%%void%%''​ functions and should be ommitted.+  * ''​%%@return%%''​ tags are not needed for ''​%%void%%''​ functions and should be omitted. 
 +  * ''​%%@return%%''​ comments should not start with the type being returned, as Doxygen will automatically add that. 
 +  * Manual formatting in ''​%%@return%%''​ tags will be lost. 
 +    * Look to Javadoc for how to describe return values in single sentences. 
 +      * e.g. "''​%%@return true if the given object represents a String equivalent to this string, false otherwise.%%''"​ 
 +    * If a set of discrete values can be returned, adding a set of ''​%%@retval%%''​ details might be considered. 
 +  * For functions mentioned in the text of a comment to be recognized, instead of ''​%%@ref%%''​ just add parenthesis to the end of the name, e.g. ''​%%someFunction()%%''​. 
 +  * For types, globals, defines, etc. mentioned in the text of comments to be recognized, they normally need to be prefixed with proper scope, most commonly ''​%%::​%%''​ 
 +    * e.g. "''​%%@return ::​CA_STATUS_OK if successful, ::​CA_MEMORY_ALLOC_FAILED if memory allocation fails, otherwise some other error value.%%''"​
  
 ===== References ===== ===== References =====
efficient_doxygen_comments.txt · Last modified: 2015/08/12 18:25 by Jon A. Cruz