• View
• Edit
• History
• Print

Please refer to this style guide for using Doxygen file and function header tags
http://mesos.apache.org/documentation/latest/doxygen-style-guide/

I prefer to use the @tag style. Here is a list of available tags (i.e. special commands): http://www.doxygen.nl/manual/commands.html.

Commonly Used Tags

• @brief: Should be a one-line, very concise description of the function.
• @param: Input parameters to the function. One tag for each parameter. Use like so: "@param <parameter.name> <description>"
• @return: Describe the value the function returns. Name not included in the format. Use like so: "@return <description>
• @retval: Describe the value the function returns, including the name. Use like so: "@retval <variable.name> <description>"

We could also make use of various attention-getting or listing tags in order to notate important work items that need to be handled, such as @bug and @todo.

Samples

Place descriptive headers above each .c file function. New code files you create will need a file header as well.

Sample function header:

/*  @brief Sets a PMIC register to the given value 
 * 
 *  Sets a PMIC control register value.  This is a blocking 
 *  call in which SPI transaction completion is awaited. 
 * 
 *  @param addr :register address 
 *  @param data :byte payload that is to be sent 
*/

Sample file headers:

/** 
 * @file file.h 
 * @brief SPI module I/O map 
 *  
 * @version <versionnum if applicable> 
 * @copyright Copyright (c) 2019 My Company. All rights reserved. 
 * 
 * 
 *                                 IMPORTANT NOTICE 
 * 
 * 
 * <legalese text here> 
 * 
 */ 

/**
 * @file <e.g. filename.c>
 *
 * @brief <add short description>
 *
 * @author <e.g. Bob or initials bbb>
 *
 * @date <add creation date or list of modification dates, no format specified>
 * @date <may use multiple date tags if desired>
 *
 * @version <version number if relevant>
 *
 * @details <detailed description, log changes, etc>
 *   Version    Date    Author    Details
 *   <add lines as necessary>
 *
 * @copyright Copyright (c) 2020 My Company, all rights reserved.
 *
 * @remark <if appropriate, include clarifying rights statements or instructions 
 *   for partners/customers receiving source, etc.>
 *
 */

You may want to sometimes comment a variable for Doxygen, and put it AFTER the declaration. This is done one of two ways:

int var; /**< Brief description after the member  */ 
int var; //!< Brief description after the member  

Running Doxygen Independently

Install Doxygen in your development environment. On Ubuntu, this can be done with sudo apt install doxygen.

Doxygen uses a configuration file to know how to build the documentation set. A default version of this file can be generated with doxygen -g <filename>.

Edit this Doxyfile to identify the source path, document output path and other options to set up the file generation correctly. Recommended minimum set of options to review:

• PROJECT_NAME
• PROJECT_BRIEF
• OUTPUT_DIRECTORY
• FULL_PATH_NAMES
• INPUT
• FILE_PATTERNS
• RECURSIVE
• EXCLUDE
• HAVE_DOT

Run the document generation using doxygen Doxyfile and the documentation will go to the location specified with OUTPUT_DIRECTORY.

Adding Doxygen to Scons

Top Level

# Give user the option to generate Doxygen files
# Always builds if option is selected
AddOption('--dox',
          dest='dox',
          action='store_true',
          default=False,
          help='If given, generate Doxygen files')
if GetOption('dox'):
    print '## DOXYGEN IS ON  ##'
else:
    print '## DOXYGEN IS OFF ##'

Project Level

# LOCATIONS
PROJECT_DIR = Dir(".")
SOURCE_DIR = PROJECT_DIR.Dir("src")
OUTPUT_DIR = PROJECT_DIR.Dir("output")
VARIANT_DIR = OUTPUT_DIR.Dir("build")

# DOXYGEN
DOXYGEN_DIR = OUTPUT_DIR.Dir("doxygen")
DOXYFILE_NAME = PROJECT_DIR.File("Doxyfile")


"""
Perform Doxygen doc generation with --dox command option
"""
if GetOption('dox'):    
    doxyfile_builder = Builder(action = 'doxygen $SOURCE' )
    env.Append(BUILDERS = {'Doxygen' : doxyfile_builder})
    env.Doxygen(DOXYGEN_DIR, DOXYFILE_NAME)
    # Always builds if --dox is given
    env.AlwaysBuild(DOXYGEN_DIR)

# Always cleans if -c regardless of --dox command line option
env.Clean(DOXYGEN_DIR, DOXYGEN_DIR)