How to use Doxygen to generate documentation for our code

From KratosWiki
(Difference between revisions)
Jump to: navigation, search
Line 35: Line 35:
 
   };
 
   };
  
The class description will be more helpful if its author explains what the class does and how to use it. 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'''.
+
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'''.
  
 
== Function documentation ==
 
== 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''.
 +
     
 +
  /** Working space dimension. for example a triangle is a 2
 +
      dimensional shape but can be used in 3 dimensional space.
 +
      @return SizeType, working space dimension of this geometry.
 +
    */
 +
  inline SizeType WorkingSpaceDimension() const
 +
  {
 +
  ....
 +
  }
 +
 +
 +
 +
  /// Calculate the maximum time step that satisfies the Courant-Friedrichs-Lewy (CFL) condition.
 +
  /**
 +
    @param CFL The upper limit for the Courant number
 +
    @param dt_max Maximum admissible time step (upper bound to be used for situations with very low velocity fields)
 +
    @return A time step value that satisfies the CFL condition for the current mesh and velocity field
 +
  */
 +
  double EstimateDt(double CFL, double dt_max)
 +
  {
 +
  ....
 +
  }
  
 
== Other useful commands ==
 
== Other useful commands ==

Revision as of 15:40, 26 January 2011

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.

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.

 /** Working space dimension. for example a triangle is a 2
     dimensional shape but can be used in 3 dimensional space.
     @return SizeType, working space dimension of this geometry.
   */
 inline SizeType WorkingSpaceDimension() const
 { 
  ....
 }


 /// Calculate the maximum time step that satisfies the Courant-Friedrichs-Lewy (CFL) condition.
 /**
    @param CFL The upper limit for the Courant number
    @param dt_max Maximum admissible time step (upper bound to be used for situations with very low velocity fields)
    @return A time step value that satisfies the CFL condition for the current mesh and velocity field
  */
 double EstimateDt(double CFL, double dt_max)
 { 
  ....
 }

Other useful commands

Grouping into modules

See also

The todo list

Documenting Kratos classes

Using the header templates

What to document?

Our aim for Kratos would be, at least, having a complete documentation for all classes and public methods. An important detail is ensuring

Personal tools
Categories