Differences between revisions 11 and 12
Revision 11 as of 2011-12-04 14:15:49
Size: 6259
Comment:
Revision 12 as of 2019-04-30 12:00:41
Size: 6243
Comment: updated doxygen home page link
Deletions are marked like this. Additions are marked like this.
Line 1: Line 1:
'''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 http://www.stack.nl/~dimitri/doxygen/. Here only some basic suggestions of how to document your code will be given. '''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 http://www.doxygen.nl. Here only some basic suggestions of how to document your code will be given.

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 http://www.doxygen.nl. 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:

  • have the doxygen executable installed on your computer (this is already done on our DESY machines)

  • document your code
  • create a configuration file
  • run doxygen to create the documentation (HTML or LaTeX based).

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.

  • (!) Note that the actual documentation consists in comments you write in the header file (!)

What you should in any case document is:

  • who is the author of the class (Marlin processor, etc) and the last modification date
  • what is the purpose of your class
  • how it can be used (and/or possible caveats)
  • what are the methods of the class good for? (Even if it seems trivial for you, don't be lazy, and tell it also other people)
  • if you use special algorithms or if your class is based on certain assumptions, document them

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.
        */
    myClass();
    /** My constructor. Initializes the coordinates.
        */
    myClass(float x, float y, float z);
    /** Default destructor.
        */
    ~myClass();


  public:
    /**Print out the private members of the class
        */
    void print();
    /**Calculate distance from origin.
       The distance is calculated with the formula
        \f$\sqrt{(x-x0)^2+(y-y0)^2+(z-z0)^2}\f$.
        @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);

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

};

#endif

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:

  • the name of your project:

PROJECT_NAME = 'your project name'
  • the input files (relative to the directory where you run doxygen):

INPUT = ../include ../src
  • the directory where to put the documentation (if you leave it empty, then the documentation will be created in the directory where you run doxygen):

OUTPUT_DIRECTORY = 'your output directory'
  • the type of documentation you want to generate (HTML, LaTeX and/or something else):

GENERATE_HTML = YES
  • If HTML chosen, the following tells doxygen where to put the html documentation relative to OUTPUT_DIRECTORY:

HTML_OUTPUT = html/

and

HTML_FILE_EXTENSION = .html

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)