写这一节的时候，我在想网上有众多的参考文献，外加官网上的，要是我再将它们重复一遍，也没什么意思。网上资料很多，但是他们有一个共同的缺点是都是罗列用法，然后显示效果。这些都是比较散的，我想是不是可以结合一个具体的范例来讲解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\tableofcontentsLeading text.\section sec An example sectionThis page contains the subsections \ref subsection1 and \ref subsection2.For more info see page \ref page2.\subsection subsection1 The first subsectionText.\subsection subsection2 The second subsectionMore text.
*//*! \page page2 Another pageEven 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);
};

查看效果。

Doxygen for C++使用说明——注释代码一相关推荐

DOxygen for C++使用说明——注释代码二
这一次我在谷歌搜索中检索到了Doxygen在github的仓库,进去一看,令人大喜,github仓库里含有了一个Doxygen的官方配置文件Doxyfile,于是下载下来,发现Doxyfile已经配置 ...
文档生成工具-Doxygen使用方法以及注释规则
最近接触了一款程序文档生成工具-Doxygen.在网上一搜索原来这么多人知道,打算把它的使用做一个总结,以及其注释的规则. 概述: Doxygen是一种开源跨平台的,以类似JavaDoc风格描述的文 ...
Doxygen简介及使用说明
一. Doxygen简介 Doxygen是一个程序的文档产生工具,可以将程序中的注释转换成说明文档或者说是API参考手册,从而减少程序员整理文档的时间.当然这里程序中的注释需要遵循一定的规则书写 ...
VC6自定义注释代码快捷键
过VS2003以后版本的人都有感觉,VS的UI操作提升不是一点点,但是就像相对VISTA和WIN7系统XP始终是个经典一样,VC6也是永远的经典.虽然VC6中有很多操作不是那么方便,不过我们可以想办法 ...
3.注释(代码的整洁之道)
3.注释(代码的整洁之道) 目录注释不能美化糟糕的代码用代码来阐述好注释坏注释注:代码的整洁之道PDF: https://pan.baidu.com/s/16PLDWPiusGjcUfW_j ...
基于Doxygen的C/C++注释原则
基于Doxygen的C/C++注释原则标注总述 1.文件头标注 2. 命名空间标注 3. 类.结构.枚举标注 4. 函数注释原则 5. 变量注释 6. 模块标注 7. 分组标注总述华丽的分隔线 / ...
【正则表达式】sql语句去掉注释代码
文章目录 1.美图 1.美图该方法,能在保持原有代码的情况下,比如大小写,换行,缩进等信息,去除sql中的各种注释代码如下 Pattern p = Pattern.compile("(? ...
IDEA中注释代码，注释符如何不显示在行首
1. 打开idea编辑器后,注释代码,会发现注释符在行首,导致版面很难看 2. 点击File->Settings,如图所示 3. 在弹出的窗口中左侧栏的搜索框中输入code style进行搜索, ...
vscode注释代码后无法将其折叠，在注释掉的代码前后分别加上//#regin和//#endregion
vscood注释代码后无法将其折叠,在注释掉的代码前后分别加上//#regin和//#endregion

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