Using Doxygen

Doxygen is a documentation system [for C++, IDL (Corba, Microsoft, and KDE-2 DCOP flavors) and C] which SAS has adopted it as its code documentation tool. This page provides a summary of some of the things you'll need to know. For more detailed information - and to download the doxygen program - go to the Doxygen website.

Briefly, Doxygen can:

  • Generate an on-line documentation browser (in HTML) and/or an off-line reference manual from a set of documented source files. Documentation is extracted directly from the sources, making it is easier to keep documentation consistent with the source code. It also supports generating output in RTF (MS-Word), Postscript, hyperlinked PDF, compressed HTML, and Unix man pages.
  • Be configured to extract the code structure from undocumented source files, enabling you to quickly find your way in large source distributions. The ability to automatically generate and include dependency graphs, inheritance diagrams, and collaboration diagrams enable relations between various elements to be visualized. 
  • Be used to create normal documentation.

Doxygen Comment Style

Two different styles can be used for doxygen comments:

  • Qt style, where special documentation blocks look like:

     /*!
    ... text ...
    */

and the one line version:

//! ... one line of text ...

  • JavaDoc style, where special documentation blocks look like: 

    /**
      * ... text ...
      */

and the one line version: 

/// ... one line of text ...

For example:

Note: This example only deals with how the doxygen comments should be used; information that should be included in standard C++ comments is a different matter, and is not addressed here.  See the SAS Recommendations for Code Documentation for more information.

/** @file Template.h
* @brief Declaration of class Template
*
* $Header: /nfs/slac/g/glast/ground/cvs/workbook/pages/advanced_doxygen/usingDoxygen.htm,v 1.1.1.1 2007/06/29 15:03:16 chuckp Exp $
*/
#ifndef CLASSTEMPLATE_H
#define CLASSTEMPLATE_H

// [C Headers]
extern "C" {
}

// [C++ Header files]
#include "SomeClass.h"

// [forward declarations]
class AnotherClass;

/** 
* @class ClassTemplate
*
* @brief This is an example class.
*
* This comment block is @e required for all class declarations.
* Please remove comments that are bracketed by [..]. These comments are there 
* to provide instructions to developers while writing their code. 
* Obvious member variables and functions, such as get and set routines and 
* default constructors and destructors, should not be documented as this 
* clutters the files. Use standard C++ comments for those comments you wish 
* Doxygen to ignore. If the class has many members - you may consider 
* providing separate public, protected, private sections for member functions
* and member variables to improve readability. In addition it may be useful to
* form member groups preceded by a header as shown below.
*
* Please note that the \$Header\$ keyword specified below is a RCS keyword, 
* and will inflate into the version, name, etc for this file.
* 
* @author Some Body
* 
* $Header $
*/

class ClassTemplate {

public:
ClassTemplate();
~ClassTemplate();

int getIntMember() { return m_intMember; };
void setIntMember(const int i) { m_intMember = i; };

/**
* Provide detailed desciption of this function
* @param parmeter1 Describe this parameter

* Here is an example of inserting a mathematical formula into the text:
* The distance is computed as /f$\sqrt{ (x_2-x_1)^2 + (y_2 - y_1)^2 }/f$
* If we wanted to insert the formula centered on a separate line:
* /f[
* \sqrt{ (x_2-x_1)^2 + (y_2 - y_1)^2 }
* /f]
* Please note that all formulas must be valid LaTeX math-mode commands. 
* Additionally, to be processed by Doxygen, the machine used must have 
* LaTeX installed. Please see the Doxygen manual for more information 
* about installing LaTeX locally.
*/
void publicMemberFunction(int parameter1);

/**
* Provide a detailed description of this function.
* @return Describe the return values.
*/
bool anotherPublcMemberFunction();

static int getStaticIntMember() { return s_staticIntMember; };

/** @name Header for Group1
* [ Description of Group1 ]
*/
//@{
// [ members of Group1]
bool yetAnotherFunction1();
int yetAnotherFunction2();
//@}

private:

/// Provide a description of this class member 
/// [note that the m_ prefix is not used for static members]
static int s_staticIntMember;
/// Provide a description of this class member
int m_intMember;
/// Provide a description of this class member
float m_floatMember;

}

#endif // CLASSTEMPLATE_H 

and the file src/ClassTemplate.cxx looks like

/** @file Template.cxx
* @brief Definition of class Template
*
* $Header: /nfs/slac/g/glast/ground/cvs/workbook/pages/advanced_doxygen/usingDoxygen.htm,v 1.1.1.1 2007/06/29 15:03:16 chuckp Exp $
*/
// File and Version Information:
// $Header: /nfs/slac/g/glast/ground/cvs/workbook/pages/advanced_doxygen/usingDoxygen.htm,v 1.1.1.1 2007/06/29 15:03:16 chuckp Exp $
//
// Description:
// ClassTemplate provides an example of code documentation for the 
// implementation of a class. These comments will not be processed by
// Doxygen - but are here for developers to identify this source file.
//
// Note that those sections of the method comment headers that are unused,
// may be omitted
//
// Author(s):
// Author1 
// Author2 

#include "PackageName/ClassTemplate.h"

int ClassTemplate::s_staticIntMember;

ClassTemplate::ClassTemplate() {
}

ClassTemplate::~ClassTemplate() {
}

void ClassTemplate::publicMemberFunction(int parameter1) {
// Purpose and Method: This routine is an example public member function.
// Inputs: parameter1 is an example input parameter
// Outputs: None
// TDS Inputs: None
// TDS Outputs: None
// Dependencies: None
// Restrictions and Caveats: None

// [Code inside function should be documented using standard C++ comments]
}

bool ClassTemplate::anotherPublicMemberFunction() {
// Purpose and Method: This routine is an example execute routine for a 
// Gaudi algorithm.
// Inputs: None
// Outputs: A bool, where true denotes something and false denotes 
// something else.
// TDS Inputs: None
// TDS Outputs: None
// Dependencies: None
// Restrictions and Caveats: None

// [Code inside function should be documented using standard C++ comments]
}

Using Mainpage.h Files

In the example given above, note the link entitled "mainpage" pointing to index.html, a special page where you can add documentation concerning all the classes described by your doxygen page.  In this example only a single class is shown; however, you can use doxygen on as many different classes as you choose. 

It is recommended that doxygen pages be created for each of the GLAST CMT packages,  using this mainpage to describe each of the package in question. To add content to the mainpage, use the doxygen special command \mainpage.

To enhance the documentation you produce, there are a variety of doxygen special commands placed inside doxygen comments.  For example, in the class description, note the doxygen special command \author.  

The command \mainpage specifies that the contents of that comment will be used to fill the  main page.  Doxygen allows this command to be placed in which ever comment you want.  The GLAST convention, however, is to:

  • Place the command in a file called mainpage.h. 

This mainpage.h file should consist only of a comment with the \mainpage command.

  • Place the mainpage.h file in the src directory.

So for our templates package we have created a file src/mainpage.h which looks like

/** @file mainpage.h
* @brief Definition of class Template
*
* $Header: /nfs/slac/g/glast/ground/cvs/workbook/pages/advanced_doxygen/usingDoxygen.htm,v 1.1.1.1 2007/06/29 15:03:16 chuckp Exp $
*/
/** @mainpage package templates
*
* @authors Documentation Task Force
*
* @section intro Introduction
* This package provides code templates for use by GLAST developers. 
* All header files for external access are located in the templates directory,
* as it is customary to put external public header files in the packageName 
* directory. Header files that are not meant for external access reside in 
* the src directory. Source files are located in the src directory. Files 
* related to loading sharable libraries are located in the src/Dll directory.
* There are 3 examples:
* 
* - User-Defined generic C++ class
* -# templates/ClassTemplate.h
* -# src/ClassTemplate.cxx
* - User-Defined Gaudi Algorithm
* -# src/ExampleAlg.cxx
* -# src/Dll/templates_dll.cxx
* -# src/Dll/templates_load.cxx
* - User-Defined Gaudi Service
* -# templates/IExampleSvc.h
* -# templates/ExampleSvc.h
* -# src/ExampleSvc.cxx
* -# src/Dll/templates_dll.cxx
* -# src/Dll/templates_load.cxx
*
*
* Also note the existence of the following directories:
* - cmt
* -# Contains the requirements file
* - doc
* -# Contains the release.notes file
*
*
* As you prepare to develop code for GLAST SAS, please be sure you are aware 
* of our current
* <A HREF="http://www-glast.slac.stanford.edu/software/CodeHowTo/codeStandards.html"> Coding Standards </A>
*
*
* If using the code in this package as an example - please modify the comments
* as appropriate for your own specific code.
*
* <hr>
* @section notes release.notes
* release.notes
* <hr>
* @section requirements requirements
* @verbinclude requirements
* <hr> 
* @todo [optionally include text about more work to be done]
* @todo Give each todo item its own line
*
*/

Note: The words after the \mainpage command are the title for the main page, and the \section command has also been introduced.  The html output from the above comment appears here.

Including Images

Another command of interest is \image, used to insert images into the documentation.   This command can be used in any comment, and the syntax is:

    \image html mypicture.gif

Notes:

  • Doxygen can also be used to create latex, man or rtf documents.  However, not all formats support all image types.  It is therefore necessary to specify which format you are outputing in which the image is to be included. 
  • The GLAST convention stipulates that all the images used in a given package must reside in a directory called doc/images/. This means that, if an image called figuresim2.gif is located in the doc/images/directory and you wish to insert it into your main page, it can be done with a simple change.

Latex and Doxygen

Latex can be used to produce formulas.  There are already some examples of this in the CalRecon code. 

Notes:

  • When using doxygen to produce documentation where latex commands are included, latex must be available on the system.  This is typically the norm on UNIX machines, but not on Windows. 
  • To download a free Windows version of latex, go to the MiKTeX website.
  • The fancyhdr package does not come with MiKTeX; you must therefore download the fancyhdr package separately from:
  • The Doxygen manual states:

Make sure the tools are available from a dos box, by adding the directory they are in to the search path....  the LaTeX is freely available set of so called macros and styles on the top of the famous TeX program (by famous Donald Knuth) and the accompanied utilities (all available for free). It is used for high quality typesetting. The result – in the form of so called DVI (DeVice Independent) file – can be printed or displayed on various devices preserving exactly the same look up to the capability of the device. The dvips allows you to convert the dvi to the high quality PostScript (i.e. PostScript that can be processed by utilities like psnup, psbook, psselect, and others). The derived version of TeX (the pdfTeX) can be used to produce PDF output instead of DVI, or the PDF can be produced from PostScript using the utility ps2pdf.

Running Doxygen

Doxygen can be run in two ways.  Both methods require that it is installed and in your path.  For information on downloading and setting up the executables, visit the doxygen homepage.  

Doxyfile. Doxygen expects an input file, called Doxyfile, an ASCII file specifying a number of input parameters when running Doxygen. 

Notes:

  • A default Doxyfile is stored in the GlastPolicy package.
  • MRvcmt users, can simply click the 'create' button in the doxygen section.

This will create the html documentation for whichever package you selected.  To view the pages, click 'examine'.  If your package uses GlastPolicy, the default Doxyfile will be provided as input to Doxygen.

  • Non-vcmt users, a version of the genDoc script will automatically create the Doxygen pages for any package.

 

Last updated by: Chuck Patterson 03/23/2007