How to use Doxygen to generate documentation for our code

From KratosWiki
Jump to: navigation, search

This How To introduces the Doxygen documentation system and gives some guidelines to use it to document Kratos code

Contents

What is Doxygen?

Doxygen is system that can be used to produce documentation for our code. It reads our source code looking for comments that follow a special format, and uses that information to generate our documentation.

To document our work, all that is required is to follow some basic guidelines while writing our code. Every time we release a new Kratos version, we will run Doxygen using our source and post the result in the Doxygen Documentation page. An alternate possibility is to run Doxygen periodically on the latest svn revision and upload the result.

Basic instructions to document C++ code

There are many different Doxygen commands, which can be consulted in its reference manual. We will review here the ones that are most commonly used in the Kratos source.

Class documentation: Short description and long description

The class description is a special C++ comment placed just before the class declaration. Its contents will be used to generate the documentation. Note how the comment is identified as input for Doxygen by adding a third slash (/) character

 /// The Example class does nothing.
 class Example
 {
   Example();
   ~Example();
 };

The text after the /// will be used to describe the Example class in the documentation. In addition to the short description, we can add a detailed description with more information about the class

 /// The Example class does nothing.
 /** This class was implemented to introduce the reader to Doxygen documentation.
     Note how this detailed detailed description is just a regular C++ multiline
     comment, but starts with an extra '*'.
  */
 class Example
 {
   Example();
   ~Example();
 };

The class description will be more helpful if its author explains what the class does and how to use it instead of a simple statement of what the class is. Try to include more than what could be deduced from reading the class name. In the case of scientific code such as Kratos, the class description is a good place to briefly describe the theory behind the implementation, and possibly even include bibliographic references. Also note that you can add (a subset of) latex commands to your documentation (use \f[ ... your equation ... \f].)

Function documentation

Function documentation is fundamentally the same as the class description in the previous section. As before, we can provide a short description and a more detailed explanation. The main difference is that, for functions, we should use the detailed description to describe the input parameters and the return value (if any). To do this, we will use the Doxygen commands @param, followed by the parameter name, and @return. Some examples:

 /// Converts a value from degrees to radians.
 /** Note that no check is performed to verify that the angle is between 0 and 360,
     angles greater than 2*Pi may be obtained.
     @param Angle The angle measured in degrees
     @return The angle measured in radians
  */
 double Radians(const double Angle)
 {
    return 3.14159 * Angle / 180.0;
 }

Other useful commands

In addition to the previous commands, there are other ways to provide useful input for Doxygen. In this section, we will review some of them.

Grouping into modules

We would like to organize our documentation by applications, which will be cleaner and easier to browse. To do so, we can use Doxygen groups. First we need to define a new group for each application, which we can put in the Application.h file. For example, we could define a group in FluidDynamicsApplication.h

 ///@defgroup FluidDynamicsApplication Kratos Fluid Dynamics Application
 ///@brief The Fluid Dynamics Application contains a basic tool set for the solution of CFD problems.
 /// This continues with a detailed description...

Then, in each header we add to the application, we can add an instruction to tell Doxygen that it belongs to our application

 namespace Kratos
 {
    ///@addtogroup FluidDynamicsApplication
    ///@{
 
    // Everything we add here will appear in the Kratos Fluid Dynamics Application documentation
 
    ///@}
 }

See also

The @see command is useful to add links inside our documentation. We use it to direct the reader to related classes and functions. A typical example of where this will be useful in Kratos is to link elements with the builder and solver or scheme that uses them.

 /// A builder and solver scheme based on separating pressure and velocity Dofs
 /**
  The PressureSplittingBuilderAndSolver class...
  This class is intended to work with ASGS and VMS elements
  @see ASGS2D, ASGS3D, VMSBase
  */
 class PressureSplittingBuilderAndSolver : public BuilderAndSolver

Note that we have to use the exact class name after @see (including capitalization) to ensure that the link works.

The todo list

Use the @todo command, to mark quickly-implemented parts of the code that kind-of work so you can revise them later. All lines marked with a @todo command will appear in the todo list.

 if( mDomainSize == 2)
 {
    // Do something in 2D
 }
 else
 {
    KRATOS_ERROR(std::logic_error,"This is not implemented in 3D yet","") ///@todo Implement this in 3D
 }

Add everything you want to keep in mind to the to-do list, but please fix it (and remove the @todo) as soon as possible.

Using the Kratos header templates

We have several templates with a skeleton of class declarations, including the corresponding documentation. Using them to begin writing new classes is encouraged. Find them in /kratos/kratos/templates. Note that the header templates in particular contain several @name blocks, which are intended to organize the functions and variables in the code. As the types of functions can be confusing at first, a short description of each one is included:

  • Life Cycle: Constructors and destructor.
  • Operators: Redefinitions of C++ operators ( [],(),++,->, etc.) for new classes. Most Kratos objects shouldn't redefine operators.
  • Operations: Functions that involve the class and its members. Everything that does not fit in other categories. Most functions in Kratos classes will be of this type.
  • Access: Get() and Set() functions that affect class members.
  • Inquiry: Ask information about the status of the class' instances. Example: IsFixed().
  • Input and output: In general, functions that manipulate character strings that display information about the class. Typically, the classes that define what will be displayed by a KRATOS_WATCH()

What to document?

Our aim for Kratos would be, ideally, having a complete documentation for all classes and public or protected functions. The minimum information needed would be the one-line short description (but avoid descriptions that are less informative than reading the function name itself) and a definition of all parameters and return values if they are not straightforward. Adding some kind of comment to the private functions would be nice to serve as a reminder in future bug fixing and upgrading, especially for long or hard to understand functions.

As said before, an outline of the theory behind your implementation (even if it is just citing some references) where relevant would be useful, not to mention that it is a clear way to convey to external Kratos users what they can expect from our code.

We are aware that adding documentation to all existing functions is excessive and a waste of time, but please try to document things as you update them, and get used to documenting new code as you implement it. Keep in mind that a good documentation also increases the readability of your code.

Personal tools
Categories