Doxygen -- part 2

Documenting the code

This section covers two topics:

1. How to place comments in your code, once doxygen can include them in the generated document.
2. How to organize the content of a comment block, so that the output appearance.

Special comment block

A special comment block is marked with a number of additional, so doxygen knows it was a need to appear in the generated document
C comment blocks in the structured text.

For Python, VHDL, Fortran and Tcl code, there are additional comment convention, you can xxx

Class C language comment block

For each entity in the code, there are two (three in some cases) of the type described, together form the entity text
file, a briefdescription, and a detaileddescription, are optional. For methods and functions, a third
type of description, referred to in body description, all the methods found in the comment block or function common components.

There may be more than a brief or detailed description (but not recommended, because the order of appearance is not specified)

If the name implies, a brief description is brief, detailed, xx. In body described may also be used as described in detail
or described in a set of implementation details. For the HTML output for providing a brief description is also provided in reference to its position tooltip.

There are several ways the comment block labeled detailed description:

1. Use the Javadoc style

/**
 * ... text ...
 */

1. Using Qt style and add !:

/*!
 * ... text ...
 */

1. xxx

///
/// ... text ...
///

or

//!
//!... text ...
//!

...

For brief description, there are some possibilities:

1. In the above use the comment block \breifcommand This command ends at the end of a paragraph, and therefore a.
   After the blank line is a detailed description, examples:

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

1. If the configuration file JAVADOC_AUTOBRIEFis provided as a comment block YES, using the Javadoc style automatically opening
   starts a brief description, with a space or a line feed .exemplary time ends:

/** Brief description which ends at this dot. Details follow
 *  here.
 */

1. The third option is to use a special C ++ style comments (not span multiple lines), example:

/// Brief description.
/** Detailed description. */

or

//! Brief description.

//! Detailed description 
//! starts here.

As you can see, doxygen is quite flexible if you have more detailed description, like this:

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

They will be combined. In the description it is also true when codes of different positions. In this example, the order depending on
the order of code parsing doxygen

And many other different file systems, doxygen also allows you to define the documents placed before the members. In this way, the document can be
placed in the source file to, rather than the header file. This keeps the header file refining, and allows members those documents
more direct access. as a compromise, brief descriptions can be placed before the detailed description of the previous member definitions.

After members plus documents

If you want to record a file, structure, union, class, enum members sometimes want to block a document placed members
after or before. For this intention, you can be an extra <flag in the comment block participate in. this function of
the number is useful.

Here are some examples:

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

This block can be used after the Qt style detailed documentation block is placed other members of the same effects as well:

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

or

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

or

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

Most of the time, want is just the place after a brief description of the membership This is accomplished by the following:

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

or

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

For functions, can use @paramthe command to a recording parameter, use [in], [out], [in,outto the recording side
to the inner joint document that can be accomplished by the direction data starts:

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

And in front of the structure and meaning of the special these blocks is the same, only <shows that the members are located before the block, rather than
behind a block (block comment).

This is an example of the comment block are used:

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

Examples

This is done using C ++ style comments Qt code blocks:

//!  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);
};

breif description also includes the class, namespace, or among members of the overview file, and using the following numbers in italics. (
This can be described in the configuration file provided BRIEF_MEMBER_DESCto hide NO). brief default
described as the detailed description first sentence (this can be REPEAT_BRIEFchanged to NO tag set). on
and described in detail in Qt style, briefly described are optional.

Javadoc style documentation block and Qt style documentation block by default behavior is the same. But according to the specified Javadoc is not
true, according to specifications, the first sentence automatically as a brief description. To enable this feature needs to be
JAVADOC_AUTOBRIEFset to YES. If you enable this option and want to add a dot in the sentence but not
the end of it, after which you should add \this is an example:

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

This is the same as above the code block, this time using Javadoc style, and enabled JAVADOC_AUTOBRIEF:

/**
 *  A test class. A more elaborate class description.
 */
 
class Javadoc_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.
       */
      Javadoc_Test();
 
      /**
       * A destructor.
       * A more elaborate description of the destructor.
       */
     ~Javadoc_Test();
    
      /**
       * a normal member taking two arguments and returning an integer value.
       * @param a an integer argument.
       * @param s a constant character pointer.
       * @see Javadoc_Test()
       * @see ~Javadoc_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);
};

Similarly, if you want to Qt style documentation block of the first sentence automatically as a breif description, it can be set
QT_AUTOBRIEF.

In the other position record

In the example in the previous section, the comment block is always located in the file, class, or define a namespace declaration prior to, or in its
. Although this is usually very easy, and sometimes need to be a member of the documents placed elsewhere before or after. For file record,
this is necessary, and therefore not "in front of a file" such a thing exists.

Doxygen allows you to put your document block anywhere (except in the body of a function or unusual in a C
-style comments.

Before the document is not placed directly on a block or expense item after that, you need to place a structured document life in the block
order, which would lead to duplication of some information .. so normally you should avoid using a structured command, unless there other requirements so that
was you had to be so.

Structured command from the \start, or @, if you prefer the words of Javadoc style, plus a command name and
one or more parameters, for example, if you want to record the class Test, you can read the following document in doxygen
of enter somewhere:

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

    A more detailed class description.
*/

Here, special commands \classfor indicating the document class Test comment block comprising another structured commands are:

• \structC structure recorded
• \unionTo record the union
• \enumTo record the enumeration type
• \fnFunction to record documents
• \varTo record variable or typedef or enum values
• \defTo record#define
• \fileTo record the file
• \namespaceTo record the name space
• \packageTo record the java package
• \interfaceIDL interface to record

To record a member of a C ++ class, you need to record the class for the namespace as well. To record global C function
, typedef pre-defined, enum or processor, you must first record the file containing it (usually a header file because
that file contains information export to other source files).

Again, you want to record global object, you must first log file where they are, in other words, there must be
/*! \file */or/** @file */

This is an example:

/*! \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);

Due to the above example each comment block contains a structured order, all of the comment block may be moved to another position or
input file (such as source files), without affecting the generation of the document. Disadvantage is that the prototype will be repeated, so that all changes require
twice. For this reason, you should first consider if this is really needed, as far as possible to avoid a structured command. I
before placing contains a function normally encountered \fnan example of the comment block commands. clear \fncommand is redundant Yu, the only
cause problems.

When you order .dox, .txtor .doctime to place a comment block of files ending in, doxygen from the file list will be
hidden in this file ...

If you have a doxygen can not be resolved, but still want to record, you can use \verbincludeas is explicitly
show it ..:

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

Ensure that the script explicitly listed in the INPUT or FILE_PATTERNSincluded in the .shexpansion, and the script can
EXAMPLE_PATHfind the path settings.

Detailed comment block

Previous chapters focus on how to get doxygen comments in your code, and a brief explanation of their differences before the detailed description,
and the use of structured commands.

In this section we focus on the content of the comment block.

Doxygen supports a variety of styles to format comments.

The simplest plain text. As output at the output for a short description of

For long description, you would normally require more structures, for example, the output text blocks reasons, or simply a
table. Doxygen support Markdown syntax used for this purpose, including expanding portion Markdown Extra

To become a language-specific format, then, doxygen over Markdown supports two forms of extra marks.

1. Similar numerals Javadoc ..
2. XML tags, as specified in the standard C # ... ??

If this were not enough, doxygen also supports a subset of the HTML markup language