A Final Word of Caution About Comments Comments that state the obvious are less than useful. In fact, they can be counterproductive because the code might change and the programmer might neglect to update the comment. What is obvious to one person might be obscure to another, however, so judgment is required when adding comments. The bottom line is that comments should not say what is happening, they should say why it is happening.

	/!  A test class. 
/*!
  A more elaborate class description.
*/
 
class QTstyle_Test
{
  public:
 
    //! An enum.
    /*! More detailed enum description. */
    enum TEnum { 
                 TVal1, /*!< Enum value TVal1. */  
                 TVal2, /*!< Enum value TVal2. */  
                 TVal3  /*!< Enum value TVal3. */  
               } 
         //! Enum pointer.
         /*! Details. */
         *enumPtr, 
         //! Enum variable.
         /*! Details. */
         enumVar;  
    
    //! A constructor.
    /*!
      A more elaborate description of the constructor.
    */
    QTstyle_Test();
 
    //! A destructor.
    /*!
      A more elaborate description of the destructor.
    */
   ~QTstyle_Test();
    
    //! A normal member taking two arguments and returning an integer value.
    /*!
      \param a an integer argument.
      \param s a constant character pointer.
      \return The test results
      \sa QTstyle_Test(), ~QTstyle_Test(), testMeToo() and publicVar()
    */
    int testMe(int a,const char *s);
       
    //! A pure virtual member.
    /*!
      \sa testMe()
      \param c1 the first argument.
      \param c2 the second argument.
    */
    virtual void testMeToo(char c1,char c2) = 0;
   
    //! A public variable.
    /*!
      Details.
    */
    int publicVar;
       
    //! A function variable.
    /*!
      Details.
    */
    int (*handler)(int a,int b);
};
 

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