Writing Developer Documentation

Developer documentation should be written using Doxygen annotations directly in the source code. This allows the documentation to live with the code essentially as comments that Doxygen is able to extract automatically into a more human readable form. Doxygen requires special syntax markers to indicate comments that should be processed as inline documentation vs. generic comments in the source code. The Doxygen manual provides detailed information on the various markers available to tailor the formatting of auto-generated documentation. It is recommended that users document the classes and methods in the header file. A sample header file with specially formatted comments is shown below. You can download a copy of the file.

Listing 2 Sample C++ header file showing inline documentation using specially formatted comments.
/** @file example.h
 *  @brief Brief description of a documented file.
 *
 *  Longer description of a documented file.
 */

/** Here is a brief description of the example class.
 *
 * This is a more in-depth description of the class.
 * This class is meant as an example.
 * It is not useful by itself, rather its usefulness is only a
 * function of how much it helps the reader. It is in a sense
 * defined by the person who reads it and otherwise does
 * not exist in any real form.
 *
 * @note This is a note.
 *
 */

#ifndef EXAMPLECLASS_H
#define EXAMPLECLASS_H

class ExampleClass
{

public:
  /// Create an ExampleClass.
  ExampleClass();

  /** Create an ExampleClass with lot's of intial values.
   *
   * @param a This is a description of parameter a.
   * @param b This is a description of parameter b.
   *
   * The distance between \f$(x_1,y_1)\f$ and \f$(x_2,y_2)\f$ is
   * \f$\sqrt{(x_2-x_1)^2+(y_2-y_1)^2}\f$.
   */
  ExampleClass(int a, float b);

  /** ExampleClass destructor description.
   */
  ~ExampleClass();

  /// This method does something.
  void DoSomething();

  /**
   * This is a method that does so
   * much that I must write an epic
   * novel just to describe how much
   * it truly does.
   */
  void DoNothing();

  /** Brief description of a useful method.
   * @param level An integer setting how useful to be.
   * @return Description of the output.
   *
   * This method does unbelievably useful things.
   * And returns exceptionally useful results.
   * Use it everyday with good health.
   * \f[
   *    |I_2|=\left| \int_{0}^T \psi(t)
   *        \left\{
   *           u(a,t)-
   *           \int_{\gamma(t)}^a
   *           \frac{d\theta}{k(\theta,t)}
   *           \int_{a}^\theta c(\xi)u_t(\xi,t)\,d\xi
   *        \right\} dt
   *     \right|
   * \f]
   */
  void* VeryUsefulMethod(bool level);

  /** Brief description of a useful method.
   * @param level An integer setting how useful to be.
   * @return Description of the output.
   *
   * - Item 1
   *
   *   More text for this item.
   *
   * - Item 2
   *   + nested list item.
   *   + another nested item.
   * - Item 3
   *
   * # Markdown Example
   * [Here is a link.](http://www.google.com/)
   */
  void* AnotherMethod(bool level);

protected:
  /** The protected methods can be documented and extracted too.
   *
   */
  void SomeProtectedMethod();

private:
  const char* fQuestion; ///< The question
  int fAnswer;           ///< The answer

}; // End of class ExampleClass

#endif // EXAMPLE_H

Once processed by Doxygen and embedded in Sphinx, the resulting documentation of the class looks as shown below:

class ExampleClass

Here is a brief description of the example class.

This is a more in-depth description of the class. This class is meant as an example. It is not useful by itself, rather its usefulness is only a function of how much it helps the reader. It is in a sense defined by the person who reads it and otherwise does not exist in any real form.

Note

This is a note.

Public Functions

ExampleClass()

Create an ExampleClass.

ExampleClass(int a, float b)

Create an ExampleClass with lot’s of intial values.

The distance between

\((x_1,y_1)\) and \((x_2,y_2)\) is \(\sqrt{(x_2-x_1)^2+(y_2-y_1)^2}\).
Parameters
  • a: This is a description of parameter a.

  • b: This is a description of parameter b.

~ExampleClass()

ExampleClass destructor description.

void DoSomething()

This method does something.

void DoNothing()

This is a method that does so much that I must write an epic novel just to describe how much it truly does.

void *VeryUsefulMethod(bool level)

Brief description of a useful method.

This method does unbelievably useful things. And returns exceptionally useful results. Use it everyday with good health.

\[ |I_2|=\left| \int_{0}^T \psi(t) \left\{ u(a,t)- \int_{\gamma(t)}^a \frac{d\theta}{k(\theta,t)} \int_{a}^\theta c(\xi)u_t(\xi,t)\,d\xi \right\} dt \right| \]
Return

Description of the output.

Parameters
  • level: An integer setting how useful to be.

void *AnotherMethod(bool level)

Brief description of a useful method.

  • Item 1

    More text for this item.

  • Item 2

    • nested list item.

    • another nested item.

  • Item 3

Return

Description of the output.

Parameters
  • level: An integer setting how useful to be.

Markdown Example

Here is a link.

Protected Functions

void SomeProtectedMethod()

The protected methods can be documented and extracted too.

Private Members

const char *fQuestion

The question.

int fAnswer

The answer.