How To Use Doxygen

2019-09-22

Doxygen is the de facto standard tool for generating documentation from annotated C++ sources, but it also supports other popular programming languages (we want Python as well). As in every other software tool, the best way to learn it is to start to use it in your everyday life. There are many examples and tutorials online. Check them! However, there are different ways that you can do things. I leave this to you, select the one that suits best to your coding style. In the end, what I want is a Doxygen-enabled commented source code. To understand better, I applied Doxygen to an existing project, the hardware interface sonar. By doing this procedure, I discovered the following nice practices which you can explore. - In the case of C++ it is better to write the comments documentation in the header file (Do you think a better place?). In the implementation file, you can add more specific comments that are related to implementation details. For instance, in the header file

/// @brief This method adds two integers. 
/// @param a First integer to add. 
/// @param b Second integer to add. 
/// @return The sum of both parameters. 
int add(int a, int b);

or as I like it better ```

@brief This method adds two integers.
@param a First integer to add.
@param b Second integer to add.
@return The sum of both parameters. */ int add(int a, int b);

In the implementation file will be: ``` /// This method uses a little-known variant of integer addition known as
/// Sophocles' Scissors. It optimises the function's performance on many
/// platforms that we may or may not choose to target in the future.
/// @TODO make sure I implemented the algorithm correctly with some unit tests.
int add(int a, int b) {
  return b + a;
}

(If there is a need for explaining something specific) If you have one single file or a python script plan accordingly. - Use the appropriate tags when you use specific structures like classes, or unions or enums and describe every single variable you use in your class definition. This doesn’t apply to i inside your for-loop. Define your interface - make it friendly to others (and even yourself). Such as:

/** @brief File descriptor */
  int fd;

  /**
   * @brief Union to have a float represented as a bytes array 
   */
  union un_float32{
    float f;
    unsigned char b[4];
  } u;

  /**
   * @brief Union to have a int16 represented as a bytes array 
   */
  union un_int16 {
    int16_t i;
    unsigned char b[2];
  } x;

  /** @brief Bytes buffer for input */
  uint8_t inputBuffer[6];

  /** @brief Bytes buffer for output */
  uint8_t outputBuffer[4];

Include the proposed comment header at the begging of your file.

/**
 *
 * @file arduinoSerial.h
 *
 * \class Arduino
 * 
 * @brief This class handles the custom message communication with arduino built on
 * top of the wiringSerial library
 *
 * @author Angelos Plastropoulos
 * @date 24.07.2018
 * @todo eliminate the hardcoded values (array sizes)
 *
 */

In case that you want to include a specific page that is not part of the source code, you can add it separately as a dox file inside the relevant folder. Following the same style, you can write your guide, e.g. configuration guide, and this page will be present under the related pages section of the Doxygen site.
In your package structure, you need to add the doc folder. Inside this folder, you can have a sub-folder with dox files (if needed). To make things easier, I created a shell script, to execute Doxygen using a custom Doxyfile (Doxygen configuration) and then create a symbolic link to the index.html of the site (I found it very boring to open the folder, order by name and double-click the index.html file). Therefore, create the folder and include the script. (to run the script you need to make it executable).
Doxygen can be configured in detail using a Doxyfile. I have created a template and placed it on the root of the package. Most probably you need to edit it based on your needs.
To make our life easier I included in the Doxyfile the functionality to get the README.md file of the project and add it to the main page of the Doxygen site. So, please write detailed READMEs.

If you want to check a live example, please check this repo. Enjoy!