Создавая хтонических чудовищ, документируй

\dontinclude

The class and member declarations and definitions inside the code fragment are `remembered’ during the parsing of the comment block that contained the \dontinclude command.

For line by line descriptions of source files, one or more lines of the example can be displayed using the \line, \skip, \skipline, and \until commands. An internal pointer is used for these commands. The \dontinclude command sets the pointer to the first line of the example.

Example:
/*! A test class. */

class Test
{
  public:
    /// a member function
    void example();
};

/*! \page example
 *  \dontinclude example_test.cpp
 *  Our main function starts like this:
 *  \skip main
 *  \until {
 *  First we create a object \c t of the Test class.
 *  \skipline Test
 *  Then we call the example member function 
 *  \line example
 *  After that our little test routine ends.
 *  \line }
 */

Where the example file looks as follows:

void main()
{
  Test t;
  t.example();
}

Click here
for the corresponding HTML documentation that is generated by doxygen.

See also:
sections , , , and .

\overload [(function declaration)]

`This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.’

If the documentation for the overloaded member function is not located in front of the function declaration or definition, the optional argument should be used to specify the correct function.

Any other documentation that is inside the documentation block will by appended after the generated message.

Note 1:
You are responsible that there is indeed an earlier documented member that is overloaded by this one. To prevent that document reorders the documentation you should set to NO in this case.
Note 2:
The \overload command does not work inside a one-line comment.
Example:
class Test 
{
  public:
    void drawRect(int,int,int,int);
    void drawRect(const Rect &r);
};

void Test::drawRect(int x,int y,int w,int h) {}
void Test::drawRect(const Rect &r) {}

/*! \class Test
 *  \brief A short description.
 *   
 *  More text.
 */

/*! \fn void Test::drawRect(int x,int y,int w,int h)
 * This command draws a rectangle with a left upper corner at ( \a x , \a y ),
 * width \a w and height \a h. 
 */

/*!
 * \overload void Test::drawRect(const Rect &r)
 */

Click here
for the corresponding HTML documentation that is generated by doxygen.

\par [(paragraph title)] { paragraph }

If no paragraph title is given this command will start a new paragraph. This will also work inside other paragraph commands (like \param or \warning) without ending the that command.

The text of the paragraph has no special internal structure. All visual enhancement commands may be used inside the paragraph. The \par command ends when a blank line or some other sectioning command is encountered.

Example:
/*! \class Test
 * Normal text.
 *
 * \par User defined paragraph:
 * Contents of the paragraph.
 *
 * \par
 * New paragraph under the same heading.
 *
 * \note
 * This note consists of two paragraphs.
 * This is the first paragraph.
 *
 * \par
 * And this is the second paragraph.
 *
 * More normal text. 
 */
  
class Test {};

Click here
for the corresponding HTML documentation that is generated by doxygen.

\mainpage [(title)]

If the \mainpage command is placed in a comment block the block is used to customize the index page (in HTML) or the first chapter (in ).

The title argument is optional and replaces the default title that doxygen normally generates. If you do not want any title you can specify as the argument of \mainpage.

Here is an example:

/*! \mainpage My Personal Index Page
 *
 * \section intro Introduction
 *
 * This is the introduction.
 *
 * \section install Installation
 *
 * \subsection step1 Step 1: Opening the box
 *  
 * etc...
 */

You can refer to the main page using \ref index (if the treeview is disabled, otherwise you should use \ref main).

See also:
section , section and section .

\example

If <file-name> itself is not unique for the set of example files specified by the tag, you can include part of the absolute path to disambiguate it.

If more that one source file is needed for the example, the \include command can be used.

Example:
/** A Test class.
 *  More details about this class.
 */

class Test
{
  public:
    /** An example member function.
     *  More details about this function.
     */
    void example();
};

void Test::example() {}

/** \example example_test.cpp
 * This is an example of how to use the Test class.
 * More details about this example.
 */

Where the example file looks as follows:

void main()
{
  Test t;
  t.example();
}

Click here
for the corresponding HTML documentation that is generated by doxygen.

See also:
section .

\page (title)

Example:
/*! \page page1 A documentation page
  Leading text.
  \section sec An example section
  This page contains the subsections \ref subsection1 and \ref subsection2.
  For more info see page \ref page2.
  \subsection subsection1 The first subsection
  Text.
  \subsection subsection2 The second subsection
  More text.
*/

/*! \page page2 Another page
  Even more info.
*/

Click here
for the corresponding HTML documentation that is generated by doxygen.

Note:
The <name> argument consists of a combination of letters and number digits. If you wish to use upper case letters (e.g. ), or mixed case letters (e.g. ) in the <name> argument, you should set to . However, this is advisable only if your file system is case sensitive. Otherwise (and for better portability) you should use all lower case letters (e.g. ) for <name> in all references to the page.
See also:
section , section , and section .

\copydoc

The link object can point to a member (of a class, file or group), a class, a namespace, a group, a page, or a file (checked in that order). Note that if the object pointed to is a member (function, variable, typedef, etc), the compound (class, file, or group) containing it should also be documented for the copying to work.

To copy the documentation for a member of a class for instance one can put the following in the documentation

  /*! @copydoc MyClass::myfunction() 
   *  More documentation.
   */

if the member is overloaded, you should specify the argument types explicitly (without spaces!), like in the following:

  /*! @copydoc MyClass::myfunction(type1,type2) */

Qualified names are only needed if the context in which the documentation block is found requires them.

The copydoc command can be used recursively, but cycles in the copydoc relation will be broken and flagged as an error.

\dotfile [«caption»]

The first argument specifies the file name of the image. doxygen will look for files in the paths (or files) that you specified after the tag. If the dot file is found it will be used as an input file to the dot tool. The resulting image will be put into the correct output directory. If the dot file name contains spaces you’ll have to put quotes («) around it.

The second argument is optional and can be used to specify the caption that is displayed below the image. This argument has to be specified between quotes even if it does not contain any spaces. The quotes are stripped before the caption is displayed.

\xrefitem «(heading)» «(list title)» {text}

The first argument <key> is a identifier uniquely representing the type of the section. The second argument is a quoted string representing the heading of the section under which text passed as the forth argument is put. The third argument (list title) is used as the title for the related page containing all items with the same key. The keys «todo», «test», «bug», and «deprecated» are predefined.

To get an idea on how to use the \xrefitem command and what its effect is, consider the todo list, which (for English output) can be seen an alias for the command

 \xrefitem todo "Todo" "Todo List" 

Since it is very tedious and error-prone to repeat the first three parameters of the command for each section, the command is meant to be used in combination with the option in the configuration file. To define a new command \reminder, for instance, one should add the following line to the configuration file:

 ALIASES += "reminder=\xrefitem reminders \"Reminder\" \"Reminders\"" 

Introduction

\@

Some commands have one or more arguments. Each argument has a certain range:

  • If <sharp> braces are used the argument is a single word.
  • If (round) braces are used the argument extends until the end of the line on which the command was found.
  • If {curly} braces are used the argument extends until the next paragraph. Paragraphs are delimited by a blank line or by a section indicator.

Here is an alphabetically sorted list of all commands with references to their documentation:

The following subsections provide a list of all commands that are recognized by doxygen. Unrecognized commands are treated as normal text.

\fn (function declaration)

onlynot

If your comment block is in front of the function declaration or definition this command can (and to avoid redundancy should) be omitted.

A full function declaration including arguments should be specified after the \fn command on a single line, since the argument ends at the end of the line!

Warning:
Do not use this command if it is not absolutely needed, since it will lead to duplication of information and thus to errors.
Example:
class Test
{
  public:
    const char *member(char,int) throw(std::out_of_range);
};

const char *Test::member(char c,int n) throw(std::out_of_range) {}

/*! \class Test
 * \brief Test class.
 *
 * Details about Test.
 */

/*! \fn const char *Test::member(char c,int n) 
 *  \brief A member function.
 *  \param c a character.
 *  \param n an integer.
 *  \exception std::out_of_range parameter is out of range.
 *  \return a character pointer.
 */

Click here
for the corresponding HTML documentation that is generated by doxygen.

See also:
section and .

Заключение

В заключении хочется сказать, что анализатор прекрасно справился со своей работой и нашел много подозрительных мест, несмотря на то, что doxygen является популярным проектом и широко используется большим количеством как мелких, так и крупными компаниями. Я привел самые основные предупреждения и оставил такие неинтересные, как лишние проверки, неиспользуемые переменные и т.п. за рамками данной статьи. Стоит упомянуть, что в некоторых местах меня удивило весьма небрежное, по моему мнению, оформление кода.

Хочется пожелать читателям писать красивый, читаемый код и не допускать ошибок. И если первое целиком зависит от программиста, то со вторым может помочь анализатор. Скачать и бесплатно попробовать PVS-Studio на своем проекте можно здесь: http://www.viva64.com/ru/pvs-studio-download/

Оцените статью
Рейтинг автора
5
Материал подготовил
Андрей Измаилов
Наш эксперт
Написано статей
116
Добавить комментарий