Doxygen - LdhssRobotics/How-Tos-2015 GitHub Wiki

The maintenance and reuse of software is most effective when the software is accompanied by accurate, up-to-date documentation. Unfortunately, the discipline of updating documentation when changing software is frequently sacrificed, especially under schedule pressure.

In response to this reality, numerous automatic documentation tools have been created, allowing developers to produce their system documentation directly from their code. This still requires discipline to constantly review code comments while updating code, and during peer reviews.

We use Doxygen for our automatic documentation generation. Doxygen is broadly used in professional and open-source software organizations, and supports many languages including C++ and Java, which are used for FRC competitions.

Examples:

• The documentation for our 2015 FRC entry is right here in GitHub! Take a look!
• Documentation for WPILib APIs for C++ has also been generated by Doxygen, and can be found here.

An excellent guide for coding style and Doxygen documentation has been provided for students in the Carnegie Mellon University Computer Science Department, here.

There are MANY ways to write comments that Doxygen will pick up for documentation. See the manual. In general, we prefer the use of JavaDoc style comments.

Here are a few of the most important examples:

• Comment blocks are a C-style comment, starting with two asterisks (*). Note that if you start a line this way in Eclipse, it will auto-generate the end of the comment for you.

  /**
   * Brief comment block.
   */

- **Documentation after a member** is indicated with a left-pointer, `<` (aka left-angle-bracket). Normally, inline comments are assumed to belong to the FOLLOWING code, but this marker tells Doxygen to associate it with the PRECEDING code.

  ```C++
  const uint_32 TheAnswer = 42;    ///< The answer to Life, the Universe, and Everything

• Classes and Functions should be documented, along with their parameters. See the example in the Tags section.

Within documentation comments, special commands, or @tags, are used to provide hints about the meaning of text. There are lots of them, but for our purposes a small set will be enough. For example, the @param tag indicates that the following text describes a function parameter, and @return flags text that describes a return value.

/**
 * @brief Calculate the decimal value of a fraction.
 *
 * A brief description is used in lists and at the start of the documentation page.
 * Further description following a blank line, like this one, is treated as a
 * detailed description by Doxygen.
 *
 * @see testMe()
 * @param n   the numerator
 * @param d   the denominator
 */
double void calculateFraction(int n, int d);

Download the Windows installer here, and install normally.

This is a self-installing archive that includes the HTML and compressed HTML versions of the manual and the GUI frontend. It bundles 32-bit and 64-bit versions of doxygen.exe, and will install the right one based on the OS.¹

To install Doxygen on our software dev laptops:

• Use the Synaptic Package Manager to select and install the latest doxygen package.

  

You will require sudo or root privileges.

OR...

1. Download the linux binaries here.

2. Extract the contents of the tarball to a convenient location. (A new directory inside your Downloads folder is fine.)

3. Download a doxytag file from here, and copy it into the /bin directory

4. Open a shell window, cd to the (temporary) doxygen install folder, and issue these commands:

    chmod +x configure
    ./configure
    make install
   

Check for success, and you're done. If your install fails, ask for help from other team members or start Googling!

The eclox Eclipse plugin provides direct control of Doxygen from within the IDE.

From within Eclipse, get the plugin from the update site, http://download.gna.org/eclox/update. This is the simplest way to install the plugin²:

1. Go to Help > Install new software..., then click Add... to add the eclox repository.

2. After clicking to go to the next dialog, check the checkbox beside the eclox plugin, then Next....

3. Review the selection, accept the license, then hit Finish. You will receive a warning about unsigned content - acknowledge and carry on.

You need to configure the path to your Doxygen installation for first-time use. PATH must include the Doxygen executable's folder.

Generating documentation:

In a project, click the eclox icon, which is a blue @-sign on the toolbar.

^{Image from here.}

If your project already has a Doxyfile configured, select it. Otherwise, create one. In our projects, the documentation output should be stored in a docs or html folder at the top of the project.

¹From Doxygen download page.
²See this StackOverflow answer.