Generating source documentation involves adding documentation to your source code or an external file so DoxyPress can incorporate them into the output it generates. The following sections cover the different ways this can be done.

One way to document your code is to add special comment blocks before each class or method. The comment blocks are designated by using C or C++ style comments with additional notations so DoxyPress knows it is text which should be put in the generated output.

Comments in C like languages: Various styles of comment blocks supported by DoxyPress for C, C++, C#, Objective-C, PHP, and Java
Comments in Fortran: Fortran comment blocks
Comments in Python: Python comment blocks
Comments in Tcl: Tcl comment blocks
Structure of a Comment Block: Tags which can be used inside a comment block

Comments in C like languages

For each entity (class, method, function, etc) in the code there are two categories of documentation, brief documentation and detailed documentation. If both are supplied the brief will come first. You can specify either of these or both as needed.

For methods and functions there is also a third category of documentation called in body documentation. This consists of the concatenation of all comment blocks found within the body of the method or function.

Having more than one brief or detailed documentation is allowed but the order in which the output will appear is not specified.

Brief documentation is a short description whereas the detailed documentation is normally longer and more detailed. The "in body" documentation can also act as detailed documentation or can describe a collection of implementation details.

For the HTML output brief documentation is also used to provide tooltips at places where an item is referenced.

There are several ways to mark a comment block as detailed documentation.

The JavaDoc style consists of a C-style comment block starting with two *'s:
```
/**
 * ... text ...
 */
```
The Qt style uses an exclamation mark (!) after the opening of a C-style comment block:
```
/*!
 * ... text ...
 */
```
In both cases the intermediate *'s on subsequent lines are optional.
```
/*!
 ... text ...
 */
```
A third alternative is to use a block of at least two C++ comment lines where each line starts with an additional slash or an exclamation mark. The following are two examples. Note that a blank line ends a documentation block.
```
///
/// ... text ...
///
```
or
```
//!
//!... text ...
//!
```
Another alternative is the following, where the comment blocks is made more visible in your code by adding more asterisks. There are 2 slashes at the end of the normal comment block followed by the start of a special comment block.
```
/********************************************//**
 *  ... text
 ***********************************************/
```
or
```
/////////////////////////////////////////////////
/// ... text ...
/////////////////////////////////////////////////
```

For the brief documentation there are also several possibilities.

Use the cmdbrief command with one of the above special comment blocks. This command terminates at a blank line.

/*! \brief Brief documentation.
 *         Brief documentation continued.
 *
 *  Detailed documentation starts here.
 */

If javadoc-auto-brief is enabled then using JavaDoc style comment blocks will automatically start a brief documentation which ends at the first period followed by whitespace or a new line.
```
/** Brief documentation which ends at this period. Detailed documentation starts
 *  here.
 */
```
The same setting has the same effect for multi-line special C++ comments.
```
/// Brief documentation which ends at this dot. Detailed documentation starts
/// here.
```
Use a special C++ style comment which does not span more than one line.
```
/// Brief documentation.
/** Detailed documentation. */
```
or
```
//! Brief documentation.

//! Detailed documentation
//! starts here.
```
The blank line in the last example is required to separate the brief documentation from the block containing the detailed documentation. The javadoc-auto-brief must be enabled.

If you have multiple detailed documentation blocks they will be joined together. Documentation will also be joined together if the comments are at different places in your source code. In this case the order will depend on the order in which DoxyPress parses the code.

//! Brief documentation, which is
//! really a detailed documentation since it spans multiple lines.
/*! Another detailed documentation!
 */

DoxyPress allows you to put the documentation of members (including global functions) in front of the definition. This way the documentation can be placed in the source file instead of the header file. This keeps the header file compact and allows the implementer of the members more direct access to the documentation. As a compromise the brief documentation could be placed before the declaration and the detailed documentation before the member definition.

Documentation After Members

If you want to document the members of a file, struct, union, class, or enum, it is sometimes helpful to place the documentation block after the member instead of before. For this purpose you have to put an additional < marker in the comment block. This also works for the parameters of a function.

For example:

int var;    /*!< Detailed documentation after the member */

This block can be used to put a Qt style detailed documentation block after a member. The following are several other ways to document after the source code.

int var;    /**< Detailed documentation after the member */

or

int var;    //!< Detailed documentation after the member
            //!<

or

int var;    ///< Detailed documentation after the member
            ///<

Usually all that is needed is a brief description after a member. The following are two examples.

int var; //!< Brief documentation after the member

or

int var; ///< Brief documentation after the member

For functions you can use the cmdparam command to document the parameters and then use [in], [out], [in,out] to document the direction. For inline documentation the direction can be specified at the beginning of the documentation block.

void foo(int v /**< [in] docs for input parameter v. */);

These blocks have the same structure and meaning as the special comment blocks in the previous section. The < indicates the member is located in front of the block instead of after the block. They can only be used to document members and parameters.

They can not be used to document files, classes, unions, structs, groups, namespaces and enums themselves. Furthermore, the structural commands mentioned in the next section (like \class) are not allowed inside these comment blocks.

Here is an example:

/*! A test class */
 
class Test
{
  public:
    /** An enum type.
     *  The documentation block must appear before the enum type
     */
    enum EnumType
    {
      int EVal1,     /**< enum value 1 */
      int EVal2      /**< enum value 2 */
    };
    void member();   //!< a member function.
 
  protected:
    int value;       /*!< an integer value */
};

Examples

Here is an example of C++ code using the Qt style:

//!  A test class. 
/*!
  A more elaborate class description.
*/
 
class 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.
    */
    Test();
 
    //! A destructor.
    /*!
      A more elaborate description of the destructor.
    */
   ~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 Test(), ~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);
};
 

The brief documentation is included in the member overview of a class, namespace, or file and are shown using a small italic font. This documentation can be hidden by setting brief-member-desc to NO in the project file. By default the brief documentation is the first sentence of the detailed documentation. This can be changed by setting the repeat-brief tag to NO. Both the brief and the detailed documentation are optional for the Qt style.

By default a JavaDoc style documentation block behaves the same way as a Qt style documentation block. This is not according the JavaDoc specification where the first sentence of the documentation block is automatically treated as brief documentation. To enable this behavior should set javadoc-auto-brief to YES in the project file. If you enable this option and want to put a dot in the middle of a sentence without ending it, you should put a backslash and a space after it.

Here is an example:

  /** Brief documentation (e.g.\ using only a few words). Details follow. */

The following source code is documented using the JavaDoc style and javadoc-auto-brief is set to YES.

/**
 *  A test class. A more elaborate class description.
 */
 
class Test
{
  public:
 
    /** 
     * An enum.
     * More detailed enum description.
     */
 
    enum TEnum { 
          TVal1, /**< enum value TVal1. */  
          TVal2, /**< enum value TVal2. */  
          TVal3  /**< enum value TVal3. */  
         } 
       *enumPtr, /**< enum pointer. Details. */
       enumVar;  /**< enum variable. Details. */
       
      /**
       * A constructor.
       * A more elaborate description of the constructor.
       */
      Test();
 
      /**
       * A destructor.
       * A more elaborate description of the destructor.
       */
     ~Test();
    
      /**
       * a normal member taking two arguments and returning an integer value.
       * @param a an integer argument.
       * @param s a constant character pointer.
       * @see Test()
       * @see ~Test()
       * @see testMeToo()
       * @see publicVar()
       * @return The test results
       */
       int testMe(int a,const char *s);
       
      /**
       * A pure virtual member.
       * @see 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);
};
 

External Documentation

In the preceding examples the comment blocks were located in front of the declaration or definition of a class or namespace or in front or after one of its members. Sometimes it is not possible or it is not desired to locate the documentation in the source code.

DoxyPress allows you to put your documentation blocks almost anywhere. The exceptions are inside the body of a function or inside a normal C style comment block.

When the documentation is located in a separate location or file structural commands will be required. Structural commands start with a backslash or an at-sign followed by a command name and one or more parameters. For example, to document the class Test put the following documentation block somewhere in an input file which will be read by DoxyPress.

/*! \class Test
    \brief A test class.

    A more detailed class description.
*/

The structural command \class is used to indicate the comment block contains documentation for the class Test.

Other structural commands are as follows:

\struct to document a C-struct.
\union to document a union.
\enum to document an enumeration type.
\fn to document a function.
\var to document a variable or typedef or enum value.
\def to document a #define.
\typedef to document a type definition.
\file to document a file.
\namespace to document a namespace.
\package to document a Java package.
\interface to document an IDL interface.

Refer to section General Commands for detailed information about these commands.

To document a member of a C++ class you must also document the class itself. The same holds true for namespaces. To document a global C function, typedef, enum or preprocessor definition you must first document the file which contains the entity.

Note

To document global objects (functions, typedefs, enum, macros, etc), you must document the file in which they are defined. You must use one of the following:

/*! \file */

or

/** @file */

Here is an example of a C header named structcmd.h that is documented using structural commands:

/*! \file structcmd.h
    \brief A Documented file.
    
    Details.
*/
 
/*! \def MAX(a,b)
    \brief A macro that returns the maximum of \a a and \a b.
   
    Details.
*/
 
/*! \var typedef unsigned int UINT32
    \brief A type definition for a .
    
    Details.
*/
 
/*! \var int errno
    \brief Contains the last error code.
 
    \warning Not thread safe!
*/
 
/*! \fn int open(const char *pathname,int flags)
    \brief Opens a file descriptor.
 
    \param pathname The name of the descriptor.
    \param flags Opening flags.
*/
 
/*! \fn int close(int fd)
    \brief Closes the file descriptor \a fd.
    \param fd The descriptor to close.
*/
 
/*! \fn size_t write(int fd,const char *buf, size_t count)
    \brief Writes \a count bytes from \a buf to the filedescriptor \a fd.
    \param fd The descriptor to write to.
    \param buf The data buffer to write.
    \param count The number of bytes to write.
*/
 
/*! \fn int read(int fd,char *buf,size_t count)
    \brief Read bytes from a file descriptor.
    \param fd The descriptor to read from.
    \param buf The buffer to read into.
    \param count The number of bytes to read.
*/
 
#define MAX(a,b) (((a)>(b))?(a):(b))
typedef unsigned int UINT32;
int errno;
int open(const char *,int);
int close(int);
size_t write(int,const char *, size_t);
int read(int,char *,size_t);

Each comment block in the example contains a structural command. This means all the comment blocks can be moved to another location or input file without affecting the generated output.

The disadvantage of this approach is that prototypes are duplicated. When you have comment blocks in a file with an extension of .dox, .txt, or .doc then DoxyPress will hide these files from the file list.

If you have a file DoxyPress can not parse but still would like to document it, you can show it as-is using \verbinclude.

/*! \file myscript.sh
 *  Look at this nice script:
 *  \verbinclude myscript.sh
 */

Make sure the script is explicitly listed in the input-source or ensure input-patterns includes the .sh extension and the script can be found in the path set via example-source.

Comments in Fortran

When using DoxyPress for Fortran code set optimize-fortran to YES in your project file.

The parser tries to guess if the source code is fixed format Fortran or free format Fortran code. This may not always be correct. If not one should use EXTENSION_MAPPING to correct this. By setting EXTENSION_MAPPING = f=FortranFixed f90=FortranFree files with extension f are interpreted as fixed format Fortran code and files with extension f90 are interpreted as free format Fortran code.

For Fortran "!>" or "!<" starts a comment and "!!" or "!>" can be used to continue a one line comment into a multi-line comment.

The following 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

As an alternative you can also use comments in fixed format code as shown below:

C> Function comment
C> another line of comment
      function a(i)
C> input parameter
        integer i
      end function A

Comments in Python

DoxyPress commands are not supported in Python documentation strings. Python has an established way of documenting source code using documentation strings called a docstring. Since a docstring is not stripped form the source programmers can inspect these comments at run time.

DoxyPress will extract the docstrings and use them as the comments in the generated documentation. None of the standard DoxyPress commands are supported.

"""@package py_docString
Documentation for package using docString comment syntax.
 
More details (docString-1).
"""
 
def func():
    """Documentation for a function.
 
    More details (docString-2).
    """
    pass
 
class PyClass:
    """Documentation for a class.
 
    More details (docString-3).
    """
   
    def __init__(self):
        """The constructor documentation."""
        self._memVar = 0;
   
    def PyMethod(self):
        """Documentation for a method."""
        pass
     

Alternate Comment Syntax

There is another way to document Python code using comments which start with "##". These comment blocks will be treated the same as comment blocks found in other programming languages which DoxyPress supports.

For Python source code set the language optimization to optimize-python in your project file.

The following listing is the same Python example using DoxyPress style comments.

## @package py_doxy
#  Documentation for package using doxy comment syntax.
#
#  More details (doxy-1).
 
## Documentation for a function.
#
#  More details (doxy-2).
def func():
    pass
 
## Documentation for a class (brief).
#
#  More details (doxy-3).
class PyClass:
   
    ## The constructor documentation.
    def __init__(self):
        self._memVar = 0;
   
    ## Documentation for a method.
    #  @param self The object pointer.
    def PyMethod(self):
        pass
     
    ## A class variable.
    classVar = 0;
 
    ## @var _memVar
    #  This is the documentation for a member variable.

Comments in Tcl

DoxyPress documentation can be included in normal Tcl comments.

To start a new documentation block start a line with ## (two hashes). All following comment lines and continuation lines will be added to this block. The block ends with a line not starting with a # (hash sign).

Brief documentation can be added with ;#< (semicolon, hash and lower then sign). The brief documentation also ends at a line not starting with a # (hash sign).

Comment blocks support all DoxyPress commands with the following two exceptions.

If a DoxyPress comment block ends with a line containing only #\code or #@code all code until a line only containing #\endcode or #@endcode is added to the generated documentation as code block.

If a DoxyPress comment block ends with a line containing only #\verbatim or #@verbatim all code until a line only containing #\endverbatim or #@endverbatim is added verbatim to the generated documentation.

To detect namespaces, classes, functions and variables the following Tcl commands are recognized. Documentation blocks can be put on the lines before the command.

namespace eval .. Namespace
proc .. Function
variable .. Variable
common .. Common variable
itcl::class .. Class
itcl::body .. Class method body definition
oo::class create .. Class
oo::define .. OO Class definition
method .. Class method definitions
constructor .. Class constructor
destructor .. Class destructor
public .. Set protection level
protected .. Set protection level
private .. Set protection level

The following is an example using DoxyPress style comments:

## \file tclexample.tcl
# File documentation.
#\verbatim
 
# Startup code:\
exec tclsh "$0" "$@"
#\endverbatim
## Documented namespace \c ns .
# The code is inserted here:
#\code
namespace eval ns {
  ## Documented proc \c ns_proc .
  # \param[in] arg some argument
  proc ns_proc {arg} {}
 
  ## Documented var \c ns_var .
  # Some documentation.
  variable ns_var
 
  ## Documented itcl class \c itcl_class .
  itcl::class itcl_class {
    ## Create object.
    constructor {args} {eval $args}
 
    ## Destroy object.
    destructor {exit}
 
    ## Documented itcl method \c itcl_method_x .
    # \param[in] arg Argument
    private method itcl_method_x {arg}{}
 
    ## Documented itcl method \c itcl_method_y .
    # \param[in] arg Argument
    protected method itcl_method_y {arg} {}
 
    ## Documented itcl method \c itcl_method_z .
    # \param[in] arg Argument
    public method itcl_method_z {arg} {}
 
    ## Documented common itcl var \c itcl_Var .
    common itcl_Var
    ## \protectedsection
 
    variable itcl_var1;#< Documented itcl var \c itcl_var1 .
    variable itcl_var2  }
 
  ## Documented oo class \c oo_class .
  oo::class create oo_class {
    ## Create object.
    # Configure with args
    constructor {args} {eval $args}
 
    ## Destroy object.
    # Exit.
    destructor {exit}
 
    ## Documented oo var \c oo_var .
    # Defined inside class
    variable oo_var
 
    ## \private Documented oo method \c oo_method_x .
    # \param[in] arg Argument
    method oo_method_x {arg} {}
 
    ## \protected Documented oo method \c oo_method_y .
    # \param[in] arg Argument
    method oo_method_y {arg} {}
 
    ## \public Documented oo method \c oo_method_z .
    # \param[in] arg Argument
    method oo_method_z {arg} {}
  }
}
#\endcode
 
itcl::body ::ns::itcl_class::itcl_method_x {argx} {
  puts "$argx OK"
}
 
oo::define ns::oo_class {
  ## \public Outside defined variable \c oo_var_out .
  # Inside oo_class
  variable oo_var_out
}
 
## Documented global proc \c glob_proc .
# \param[in] arg Argument
proc glob_proc {arg} {puts $arg}
 
variable glob_var;#< Documented global var \c glob_var\
  with newline
#< and continued line
 
# end of file

Structure of a Comment Block

The previous sections focused on how to designate documentation in your source code, the differences between brief and detailed documentation, and the use of structural commands. In this section we will examine the commands which are supported in special comment blocks to enhance the output.

DoxyPress supports various styles of formatting. The simplest form is to use plain text. This will appear as is in the output and is ideal for a short description.

For longer documentation you may want to add other formatting such as a list, a table, and font styling. DoxyPress supports the syntax of Markdown including the Markdown extra extension.

Refer to Markdown for commands and additional information

Refer to General Commands for supported commands

Refer to HTML Tags for supported HTML tags

Refer to XML Tags for supported XML tags