Doxygen Workflow

#Doxygen Workflow

Getting Started

To start generating your own doxygen code for IGVC, you first need to download doxygen. On Ubuntu this is easy, simply type:

 sudo apt-get install doxygen

to install doxygen from your linux distributions program repository, after typing in your password and successfully installing doxygen you will now be able to run all doxygen commands.

To test to see the IGVC code run, type:

 doxygen igvc_doxy_config

where igvc_doxy_config is the doxygen configuration file used to define characteristics of the doxygen documentation generated from 'doxygen igvc_doxy_config'.

Additonal Notes:

(Skip this if you aren't interested in using doxygen for your own projects)

To generate your own configuration file for your own projects type:

 doxygen -g <name_you_want_to_call_config_file>

Typically you won't have to edit much in this file, and you will be able to generate your doxygen documentation with the command shown previously on this page 'doxygen <name_of_the_configuration_file>'. We however changed four tags, FILE_PATTERNS to *.h and *.cpp so we can exclude other files not used in doxygen generation, RECURSIVE = YES, so we could recursively look for documented files in our large project, and EXTRACT_PRIVATE = YES, so we can look at doxygen comments applied to private members to classes.

To learn more about tags and getting started with Doxygen go to https://www.stack.nl/~dimitri/doxygen/manual/starting.html

Writing your own Doxygen Documentation

So now you know how to run doxygen generation to create the html files for doxygen documentation, you will need to know how to create the content in the documentation. What you will need to write comments in a way Doxygen will understand. There are many standards for doxygen documentation, however we will be using java style documention. This code looks like this:

/**
 * @file RemoteControl.h
 * @class RemoteControl
 * @brief The class which converts joy messages to twist
 *
 * This class will act as a way to take controller inputs and output them to a format which is usable by the robot.  It
 * is currently setup to accept joy messages and output them as a twist message which only sets the linear.x and
 * angular.z velocities.
 */

You should notice that all Doxygen comment blocks in this style start with a /** with each line after having a * and ending in /, IDEs like Eclipse will typically take care of this for you if you format code blocks in that fashion, so if you add a new line of documentation in between a /* and a */ it will automatically add a *.

Additionally, same line commands with @, for example commands like @brief (a "brief" description of the subject of the comment) start with @ for our standard.

Typically the majority of the doxygen commenting you will do will look like this:

 /**
 * @brief The twist publisher
 *
 * This ros publisher will be responsible for publishing the twist message which will eventually be sent to the
 * robot's motor controllers.
 */

where each of these comments is placed above a function, class, or variable. However doxygen offers more specific commands like @var, and @param for descriptions of variables and parameters for functions.

To learn more about the functionality of Doxygen comments look here https://www.stack.nl/~dimitri/doxygen/manual/docblocks.html