GtkRadiant Doxygen Documentation

# Doxygen Quick Reference

## Index

1. Commenting styles
2. Qt Style C++ Class Example
3. JavaDoc Style C++ Class Example
4. Special Tags
5. Structural Tags

## 1. Commenting Styles

There are two different styles of commenting that doxygen recognises.

Qt Style:
`/*!
.... text ....
*/
` Qt Style Single line
`//! .... one line of text ....
`

JavaDoc Style:
`/**
* .... text ....
*/
`
JavaDoc Style Single line
`/// .... one line of text ....
`

Doxygen only allows one brief and one detailed description for each declaration/definition. If there is a brief description before a declaration, and one before the a definition, only the one before the declaration will be used. If the same situation occurs for a detailed description the one before the definition is preferred and the one before the declaration will be ignored.
A useful method is to have the brief documentation with the declaration in the header file, and the detailed documentation with the definition in the source file.

Note: Standard C/C++ comments are ignored by doxygen, but will be included in the code listing for that file.

top

## 2. Qt Style C++ Class Example

Here is an example of a C++ class using Qt Style documentation.
The IEpair class from include/iepairs.h is used here. The html result of using these comments can be found here.

Note: The resulting html was generated from a single file. If it were generated as part of the whole documentation, many of the function names and variables would be hyperlinks to their definitions.

    //! Virtual class to allow plugin operations on entity pairs
    /*!
      \todo Write more complete documentation for this class so that it's use
      is clear

      An interface to entity keys and key pairs that allows plugins to;
      read and write entity keys and key values, get a key value as a
      vec3_t
    */
    class IEpair
    {
      public:
        //! Increment the number of references to this object
        virtual void IncRef () = 0;

        //! Decrement the reference count
        virtual void DecRef () = 0;

        //! Get a vector from a key
        virtual void GetVectorForKey( char* key, vec3_t vec ) = 0;

        //! Get a float from a key
        virtual float FloatForKey( char *key ) = 0;

        //! Get a string (char *) from a key
        virtual char* ValueForKey( char *key ) = 0;

        //! Set a key value to char *value
        /*!
          \param key The (char *) containing the keyname
          \param value The (char *) to set the key value to
        */
        virtual void SetKeyValue( char *key, char *value ) = 0;

        //! Get a vec3_t for the entities origin
        virtual void GetEntityOrigin( vec3_t vec ) = 0;

        //! Compute the rotated bounds of the BBox based on "angle" and "angles" keys
        virtual void CalculateRotatedBounds( vec3_t mins, vec3_t maxs ) = 0;
    };

top

## 3. JavaDoc Style C++ Class Example

The same class documented using JavaDoc Style comments

    /// Virtual class to allow plugin operations on entity pairs
    /**
      * @todo Write more complete documentation for this class so that it's use
      * is clear
      *
      * An interface to entity keys and key pairs that allows plugins to;
      * read and write entity keys and key values, get a key value as a
      * vec3_t
      */
    class IEpair
    {
      public:
        /// Increment the number of references to this object
        virtual void IncRef () = 0;

        /// Decrement the reference count
        virtual void DecRef () = 0;

        /// Get a vector from a key
        virtual void GetVectorForKey( char* key, vec3_t vec ) = 0;

        /// Get a float from a key
        virtual float FloatForKey( char *key ) = 0;

        /// Get a string (char *) from a key
        virtual char* ValueForKey( char *key ) = 0;

        /** Set a key value to char *value
          * @param key The (char *) containing the keyname
          * @param value The (char *) to set the key value to
          */
        virtual void SetKeyValue( char *key, char *value ) = 0;

        //! Get a vec3_t for the entities origin
        virtual void GetEntityOrigin( vec3_t vec ) = 0;

        //! Compute the rotated bounds of the BBox based on "angle" and "angles" keys
        virtual void CalculateRotatedBounds( vec3_t mins, vec3_t maxs ) = 0;
    };

top

## 4. Special Tags

Special tags using the Qt style begin with a " \ ", or using JavaDoc style a " @ " (the two should not be mixed).
Common special tags

author | The author or a list of comma separated authors/contributers
see | A reference to another class, class member, function, etc...
param | A description of a specific function argument or parameter
return | A description of the value returned from a function/method
bug | Starts a paragraph where one or more bugs may be listed.
note | Starts a paragraph where a note may be entered.
todo | Starts a paragraph where a TODO item is described. Note: All TODO items are collated into a separate todo list, each linking to each other
version | Starts a paragraph where one or more version strings may be entered.
warning | Starts a paragraph where one or more warning messages may be entered.
brief | A single line comment in place of the //! or /// comment.

top

## 5. Structural Tags

These are used to document a named object, and are not required to be located near that object definition or declaration. This allows the documentation for an object to be located anywhere in the doxygen input files. The exception to this rule however, is that these documentation blocks cannot be within the body of a function or within C style comment blocks. All structural commands are preceded by either a " \ " or a " @ ", depending on the documentation style, and require one or more parameters to specify the name of the object the description is referring to.

An example of the \file structural tag:

    /*! \file iepairs.h
        \brief One line documentation for this file
        \author Author(s)
        Long description of this file
    */

Common Structural Tags

class | Documents a class eg:`/*! \class IEpair \brief Short description of the IEpair class Detailed description of the IEpair class
*/
`
def | Describes a #define eg:`/*! \def MAX_VALUE The name of the define \brief Description of MAX_VALUE */
`
file | Describes a file eg:`/*! \file iepairs.h The name of the file \brief Description of the file iepairs.h Details
*/
`
struct | Documents a struct eg:`/*! \struct BTListList_t the name of the struct \brief Description of BTListList_t Details
*/
`
var | Documents a typedef, variable or enum value eg:`/*! \var typedef unsigned int UINT32 \brief Short description */
`
fn | Documents a function eg:`/*! \fn virtual void IEpair::DecRef() = 0; \brief Short description of this function Detailed description of this function */
`

top