Using Doxygen

Introduction - Doxygen Comment Style - Using Mainpage.h Files - Including Images - Latex & Doxygen - Running Doxygen

Introduction

GLAST software has adopted doxygen as our code documentation tool.  This page will give you a basic summary of some of the things you'll need to know about doxygen.  For more detailed information and to download the doxygen program, visit their website.

What's doxygen?  Well, no use duplicating introductions; this is what the doxygen webpage has to say,

"Doxygen is a documentation system for C++, IDL (Corba, Microsoft, and KDE-2 DCOP flavors) and C. 

It can help you in three ways: 

1. It can generate an on-line documentation browser (in HTML) and/or an off-line reference manual (in ) from a set of documented source files. There is also support for generating output in RTF (MS-Word), Postscript, hyperlinked PDF, compressed HTML, and Unix man pages. The documentation is extracted directly from the sources, which makes it much easier to keep the documentation consistent with the source code. 
   
2. Doxygen can be configured to extract the code structure from undocumented source files. This can be very useful to quickly find your way in large source distributions. The relations between the various elements are be visualized by means of include dependency graphs, inheritance diagrams, and collaboration diagrams, which are all generated automatically. 
   
3. You can even `abuse' doxygen for creating normal documentation." 

Doxygen Comment Style

To first step in using doxygen to insert doxygen style comments into your code.  There are two different styles you can use for doxygen comments (again, stolen shamelessly from the doxygen page)

• The Qt style, where special documentation blocks look like: 
  /*!
  ... text ...
  */
  
  
  and the one line version: 
  //! ... one line of text ...
  
  
• The JavaDoc style, where special documentation blocks look like: 
  /**
    * ... text ...
    */
  
  
  and the one line version: 
  /// ... one line of text ...

I shall use the Qt style for examples from now on, but you can use either in your code.  

There are many ways in which you can choose to use doxygen comments to document your code.  What follows, however, is one method that we feel works adequately.  Note that the following explanation only deals with how the doxygen comments should be used; the information that you should include in standard C++ comments is a different matter, which is not treated here.  See the Code Recommendations document on the Documentation Task Force Home Page for more information.

This commenting system is illustrated in the following example

#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 and Version Information:
// $Header$
//
// 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

Browsing through the documentation in the above link, you may have noticed that the link entitled "mainpage" (which points to index.html) isn't very interesting.  This is a special page where you can add documentation concerning all the classes described by your doxygen page.  In our example we only have a single class, but you can use doxygen on as many different classes as you choose.  A natural subdivision is to create doxygen pages for each of the GLAST CMT packages.  So ideally we would like this mainpage to be a description of the package in question.

So how does one add content to the mainpage?  You use the doxygen special command \mainpage.  There are a variety of doxygen special commands; they are inside doxygen comments to enhance the documentation you produce.  For instance in the class description, we have used 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 you to place this command in which ever comment you want.  However, the GLAST convention is that the command goes into a file called mainpage.h.  This mainpage.h file should consist only of a comment with the \mainpage command.  Also this mainpage.h file should reside in the src directory.

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

/** @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 that the words after the \mainpage command are the title for the main page.  We have also introduced the \section command, whose syntax you should be able to deduce.  The html output from the above comment appears here.

Including Images

The other command of interest is the \image command.  This command is used to insert images into your documentation.   The \image command can be used in any comment.  The syntax of the command is as follows

    \image html mypicture.gif

Though we have only been showing html output, 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 output format you with the image to be included in.  Let it be noted that the GLAST convention is that all the images you use in your documentation for a given package will reside in a directory called doc/images/.

Suppose then that we had an image called figuresim2.gif, in the directory doc/images/ that we wished to insert into our main page.  We could be done with a simple change

Again, see here for the resulting html output.

Latex and Doxygen

It is possible to use latex to produce formulas.  There are already some examples of this in the CalRecon code.  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, however, on Windows this is a different matter.  There is a freely available version of latex available for Windows, MiKTeX:
http://www.miktex.org/
The Doxygen manual states the following:

Make sure the tools are available from a dos box, by adding the directory they are in to the search path.  For your information, 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.

If you want to use MikTeX then you need to download the fancyhdr package separately. You can find it at:
ftp://ftp.tex.ac.uk/tex-archive/macros/latex/contrib/supported/fancyhdr/

Runnning Doxygen

You can run doxygen in two ways.  Note that both methods require you to have doxygen installed and in your path.  Visit the doxygen homepage for info on downloading and setting up the executables.  

Doxygen expects an input file, called Doxyfile.  This ASCII file specifies a number of input parameters when running Doxygen.  We have created a default Doxyfile - it is stored in the GlastPolicy package.

1) For vcmt users you can simply click the 'create' button in the doxygen section.  This will create the html documentation for whichever package you had selected.  Then click 'examine' to view the pages.  If your package uses GlastPolicy, the default Doxyfile will be provided as input to Doxygen.

2) For non-vcmt users, there will be a new version of the genDoc script.  This will automatically create the Doxygen pages for any package.

K. Young Last Modified: 08/04/2004 15:42