Fermilab


MINOS Offline Documentation
[home] [installing MINOS software] [supported platforms] [package links] [mailing list] [HyperNews] [FAQ] [computing help] [MINOS glossary] [archives]

How to document your code for doxygen



Note there are some emacs lisp macros that will help do a lot of what is described here.

Doing nothing, Doxygen will produce a nice cross referenced HTML-ized version of the code. However, you can make this even more useful by embedding documentation on how to use your classes right in the code itself. It is very easy to learn the extension to C++ comments that doxygen uses. Several styles are supported, see Doxygen's home page for more info, particularly this section for details, but an adequate subset are reproduced here.

  1. Comments can come before the code item.
  2. For class members and parameters they may also come after them.
  3. They may be either brief (one line) or detailed or both.
  4. Put the reference documentation type comments (class and method descriptions) in the .h file and not in (or, at least, in addition to) the .cxx files.

Brief comment before

Add an extra "/"
    /// This method does something
    void DoSomething();

Detailed comment before

Add an extra "*"
    /** 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();
- the intermediate leading "*"s are optional.

Brief comment after

Add an extra "/<"
    void DoSomething(); ///< This method does something

Detailed comment after

Add an extra "*<"
    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. */
- the intermediate leading "*"s are optional.

Modules or Packages

You can group a package worth of things using a single instance of "\defgroup". A good location for this is the LinkDef.h file if the package has one. It might look something like:
/** \defgroup PackageName PackageTitle
 *
 * \brief Provide some stuff to do stuff
 */
Then in all the .h openning comments (see below) add a line like:
/** ...
 *
 * \ingroup PackageName
 *
 * ...
 */

Example .h file

Below is a full example.
/**
 * \class ExampleClass
 *
 * \ingroup PackageName
 * (Note, this needs exactly one \defgroup somewhere)
 *
 * \brief Provide an example
 *
 * 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 Attempts at zen rarely work.
 *
 * \author (last to touch it) $Author: bv $
 *
 * \version $Revision: 1.5 $
 *
 * \date $Date: 2005/04/14 14:16:20 $
 *
 * Contact: bv@bnl.gov
 *
 * Created on: Wed Apr 13 18:39:37 2005
 *
 * $Id: doxygen-howto.html,v 1.5 2005/04/14 14:16:20 bv Exp $
 *
 */

#ifndef EXAMPLECLASS_H
#define EXAMPLECLASS_H

class ExampleClass
{

public:

    /// Create an ExampleClass
    ExampleClass();

    /// Create an ExampleClass with lot's of intial values
    ExampleClass(int a, float b);

    ~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 A useful method.
      * \param level an integer setting how useful to be
      * \return Output that is extra useful
      * 
      * This method does unbelievably useful things.  
      * And returns exceptionally useful results.
      * Use it everyday with good health.
      */
    void* VeryUsefulMethod(bool level);

private:

    const char* fQuestion; ///< the question
    int fAnswer;           ///< the answer 

};                              // end of class ExampleClass

#endif  // EXAMPLECLASS_H


Last Modified: $Date: 2005/04/14 14:16:20 $
Contact: minos_software_discussion@fnal.gov
Page viewed from http://www-numi.fnal.gov/offline_software/srt_public_context/WebDocs/doxygen-howto.html
Fermilab
Security, Privacy, Legal Fermi National Accelerator Laboratory