Doxygen is a documentation system for C++, C, Java, Objective-C, Python, IDL (Corba and Microsoft flavors), Fortran, VHDL, PHP and C#. For details, see Here only some basic suggestions of how to document your code will be given.

In order to generate doxygen based documentation, you need to follow four steps:

All these steps will be explained in the following.

How to document your code

It is highly recommended that you document your code. This makes your life easier not only for potential users of your code, but also for you, if you are going to reuse your code after a long period of time.

What you should in any case document is:

Bellow is an example of a dummy class:

#ifndef MYCLASS_HH
#define MYCLASS_HH

/** @brief Dummy class used for illustration purposes. Doing something with it.

    Detailed description follows here.
    @author X. XYZ, DESY
    @date March 2008
class myClass{
    /** Default constructor. Does something.
    /** My constructor. Initializes the coordinates.
    myClass(float x, float y, float z);
    /** Default destructor.

    /**Print out the private members of the class
    void print();
    /**Calculate distance from origin.
       The distance is calculated with the formula
        @param x - x coordinate of the point
        @param y - y coordinate of the point
        @param z - z coordinate of the point
        @return distance to point
    float getDistance(float x, float y, float z);

    float _x0;/**<initial x-coordinate*/
    float _y0;/**<initial y-coordinate*/
    float _z0;/**<initial z-coordinate*/



Have a look at the doxygen output. It is easy to see which is the effect of the comments.

Basically, C-style comments are used, e.g.

  Commenting something...

The doxygen \brief command was used in the class description. It ends at the end of the paragraph. You can try to delete it, to see the difference.

The methods of a class are easily described like this:

/** My function doing something...
    @param param1 first parameter
    @param param2 second parameter
    @return value return value
float myFunction(float param1, float param2){

Formulas can be inserted as in LaTeX files, but put between a pair of \f$ commands:

\f$x_0 + y^3\f$

Members of a class are documented like this:

int var; /**< Detailed description after the member */

where the sign '<' just tells doxygen that documentation follows after the member.

These are only a few very basic and easy steps which you need to follow to create/improve the documentation B) Of course, this is not the only way in which things can be done. But as you can see, you don't need to be an expert in doxygen to improve significantly the documentation which we all miss...

How to create a configuration file

Usually, the HCAL software packages already contain a doxygen configuration file, see for example /group/hcal/calice_soft/pro_test/source/calice_userlib/doc/Doxyfile, such that you don't need to create an additional one. However, if you want to do this for private purposes, you have to:

doxygen -g <config_file>

Then you can edit the default configuration file to serve your needs. The options are explained in the file. Some of the important things you need to pay attention to are:

PROJECT_NAME = 'your project name'

INPUT = ../include ../src

OUTPUT_DIRECTORY = 'your output directory'





tells what the extension of the html files should be (.htm or .html).

Here you can find an example of a Doxyfile with which the above example was generated. Have fun with it ;) and feel free to modify it according to your needs.

How to run doxygen

doxygen <config_file>

This takes a bit, probably you will see some warnings about undocumented methods, etc, which you can ignore in the first stage (you still get the documentation you added).

Suppose you decided yourself for an HTML documentation. In the directory you ran doxygen, you will get a directory called html. There, the file you are interested in is index.html. You can view it in your favourite browser. For example, open: file:///group/hcal/calice_soft/pro_test/source/calice_userlib/doc/html/index.html in your internet browser (on a FLC machine). By clicking, you can find a lot of useful information about the classes and methods present in the package calice_userlib.

How to document your code using doxygen (last edited 2019-04-30 12:00:41 by OliverSchaefer)