Doxygen for C++使用说明——注释代码一

写这一节的时候，我在想网上有众多的参考文献，外加官网上的，要是我再将它们重复一遍，也没什么意思。网上资料很多，但是他们有一个共同的缺点是都是罗列用法，然后显示效果。这些都是比较散的，我想是不是可以结合一个具体的范例来讲解Doxygen的用法呢？这样大家既可以学习到语法，也可以直接拿这个模板来用。

我自己在网上下了个模板，并且加了一些内容。这是显示效果链接。下面我将具体来介绍：

先看test.h.

/**
* \mainpage libtest
*
* \section intro_sec oFono telephony client APIs.
*
* This library provides easy to use APIs to use by hiding all details.
*
* \section install_sec Installation
*
* \subsection Download the RPM package
*
* Go to download page to download the RPM package.
*
* \subsection Install
*
* Run the following command in terminal to install:
* \code
* $rpm -ivh libtest-api.rpm
* \endcode
*
* \section usage_sec How to use this library
*
* \subsection source Include in file
*
* To use this library, you must include the headers in your source file:
* \code
* #include <test.h>
* \endcode
* If you use other interfaces, you must include it too, like message:
* \code
* #include <test.h>
* #include <test-helper.h>
* \endcode
*
* \subsection compile How to compile
*
* To build with this library you can use pkg-config to get link options:
* \code
* $pkg-config --cflags --libs test-api
* \endcode
*/
/**
* \file test.h
* \brief API interface test is in charge of path management
*
* It provides APIs to query path list and to query properties for a specific path.
*
* \note
* This interface requirs to run in main loop thread because some GLib dependency.
*
* Besides, you should keep main loop idle for most of times in order to get callbacks and make sure
* libtest-api process signals successfully. This means you should put business logic into a separate
* thread.
*/
#ifndef _TEST_H
#define _TEST_H

/**
* \enum API_RESULT_CODE Indicating whether API operation succeed or fail.
*/
enum API_RESULT_CODE {
API_SUCCESS, /**< API call is successfully */
API_FAILED, /**< API call is failed */
};

/**
* \brief Initialize libtest-api.
*
* This function should be the first one to call when using libtest-api. It does essential initializations.
* This function is synchronous.
*
* \return #API_RESULT_CODE indicating whether this call success or failed.
*
* \see test_deinit
*
* \par Sample code:
* \code
* if (test_init() != OFONO_API_SUCCESS) {
*     printf("error occurred, failed to init test\n");
*     return;
* }
* // operations goes here
* if (test_deinit() != OFONO_API_SUCCESS) {
*     printf("failed to deinit \n");
*     return;
* }
* \endcode
*/
int test_init();

/**
* \brief Finalize libtest-api
*
* This function is designated to be called when no longer needs libtest-api to release resources in libtest
* and do some finalization.
*
* \note
* It is an error to call any APIs after calling test_deinit()
*
* \return #API_RESULT_CODE indicating whether this call success or failed.
*
* \see test_init
*/
int test_deinit();

/**
* \brief Obtain current list of path
*
* \param [out] paths a pointer to an array of strings
* \param [out] count indicating the count of path.
*
* \note
* This function will allocate memory for path array. So caller must free the array, but should not free each item.
*
* \return #API_RESULT_CODE indicating whether this call success or failed.
*
* \par Sample code:
* \code
*    char **path = NULL;
*    int count = 0;
*    test_get_paths(&path, &count);
*    // use the path
*    free(path);
*    path = NULL;
* \endcode
*/
int test_get_paths(char ***paths, int *count);

#endif

以上为代码，下面我们将具体说说。

\mainpage

一般我们为一个C++项目建立一个说明文档，首先应该有个总的项目说明，简要介绍项目的背景、安装路径、使用方法等。这时我们可以在\mainpage中完成。它的语法为：

用法：

\mainpage [(title)]

（Qt风格）示例：

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

查看效果。

效果与上一模一样的(JavaDoc风格)的代码如下：

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

最上面我们给的源码实际上使用的是JavaDoc风格。

一般， JavaDoc以两个**开头：

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

Qt 风格以*!开头

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

两种用法，注释块中间的星号是可选, 所以将注释块写成:

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

\section

用法：

\section <section-name> (section title)

说明：

section-name为索引名，section title为章节的标题

我们再介绍一个和\mainpage相似的概念。

\page

用法：

\page <name> (title)

示例：

/*! \page page1 A documentation page
\tableofcontents
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.
*/

查看效果。

注意：里面的 \ref 是索引的意思。

\code

用法：

\code [ '{'<word>'}']

示例：

\code{.py}
class Python:
pass
\endcode

\code{.cpp}
class Cpp {};
\endcode

\brief

用法：

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

如果JAVADOC_AUTOBRIEF 被设置为 YES，则JavaDoc风格将注释块中的第一个句子视为简要描述, 这个句子可以以句号’.’、空格或者空行来结束:

用法：

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

类的注释

如下为使用Qt风格的C++代码注释。

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

查看效果。