Commenting Your Programs Documenting the code
Here is an example of a documented piece of C++ code using the Qt style: Click here for the corresponding HTML documentation that is generated by doxygen.
For Fortran "!<" or "!>" starts a comment and "!!" or "!<" can be used to continue an one line comment into a multi-line comment.

Here is an example of a documented Fortran subroutine:

Here is an example of a documented Fortran subroutine:

!> Build the restriction matrix for the aggregation 
!! method.
!! @param aggr information about the aggregates
!! @todo Handle special case
subroutine intrestbuild(A,aggr,Restrict,A_ghost)
  implicit none
  Type(SpMtx), intent(in) :: A !< our fine level matrix
  Type(Aggrs), intent(in) :: aggr
  Type(SpMtx), intent(out) :: Restrict !< Our restriction matrix
  !...
end subroutine


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.

Comments can come before the code item.
For class members and parameters they may also come after them.
They may be either brief (one line) or detailed or both.
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