单击Diagrams标签,如果已经安装了GraphViz,则保持默认,如果没安装,则选择“Use built-in class diagram generator”,如图4所示:
单击Expert按钮,会弹出一个有更多标签页的对话框,在"Project"标签页下,将OUTPUT_LANGUAGE设置为Chinese,因为我需要生成中文文档,如图4所示:
单击"Input"标签,将INPUT_ENCODING保持默认的utf-8,因为我用的是Visual Studio源代码文件的编码默认就是utf-8。如图5所示:
如果你有洁癖,你可以耐心的将FILE_PATTERNS下的后缀一个一个删掉(用记事本打开配置文件,搜索”FILE_PATTERNS”,一下可以删除一片,免去你点鼠标点到食指抽筋之苦),只留下*.h、*.hpp、*.c、和*.cpp等,意思是只扫描C++头文件和源文件,如图6所示:
下拉滚动条,会有EXCLUDE和EXCLUDE_PATTERNS表示不要进行解析的目录和文件,即工程目录下有的目录不需要进行文档化(比如测试代码),就用这两个排除掉。单击“Source Browser”标签,勾选“SOURCE_BROUSER”,这样文档中就会附加一份源码,方便随时查阅,如图7所示:
单击"HTML"标签,勾选“HTML_DYNAMIC_SECTION”,表示要输出chm文件,同时在CHM_FILE输入文件名作为要最终生成的chm文件名,旁边的那个"File.."按钮其实没用。同时点击“HHC_LOCATION”右边的按钮找到chm编译器hhc.exe。如图8所示:
最后,还要用记事本打开这个配置文件,找到JAVADOC_AUTOBRIEF,将它的值改为YES,即支持JavaDoc的语法,这样就可以用熟悉的JavaDoc风格的文档注释了。
2. 常用注释语法
注释写在对应的函数或变量前面。
简要注释和详细注释:
/**
* @brief Brief Description.
*
* Detailed Description
*/
简要注释和详细注释用一个空行隔开。
JavaDoc风格下,自动会把第一个句号前的文本作为简要注释,后面的为详细注释。你也可以用空行把简要注释和详细注释分开。注意要设置JAVADOC_AUTOBRIEF设为YES。
为了注释一个类中的member,首先要对该类作注释。同样的问题上升到namespace。要注释一个全局的function,typedef,enum或preprocessor定义,你需要首先定义(只能用@file,因为文件不再任何东西里面,就只能用特殊命令实现了,而不像类、函数等,既可以在上方放注释,也可以用@class、@fn进行注释)包含它的文件。
(1)文件头注释
/** @file [file-name]
*@brief brief description.
* @author <list of authors>
* [@author <authors description>]
* @date <date>
* @version <version number>
*
* detailed description for test.cpp
*/
一般@file后我们空着,Doxygen会默认为是@file所在文件的文件名。
[]表示可选,{}表示重复0到N次,<>表示必须参数。@author 表示作者,@data表示日期,@version表示版本号。
(2)类注释
/**
* @class <class-name> [header-file] [<header-name]
* @brief brief description
*
* detailed description
*/
header-file是类声明所在的头文件名字,header-name是要显示的链接文字,一般为头文件的真实路径。
(3)函数注释
/**
* @brief brief description.
* {@param <parameter-name> <parameter description>}
* @exception <exception-object> <exception description>
* {@exception <exception-object> <exception description>}
* @return <description of the return value>
* {@return <description of the return value>}
* @note <text>
* @remarks <remark text>
* {@remarks <remark text>}
* [@deprecated <description>]
* [@since when(time or version)]
* [@see references{,references}]
*/
@可用/代替,但我倾向于用@。
@param 参数名及其解释(我还习惯在param后加[IN]表示输入还是输出参数)
@exception 用来说明异常类及抛出条件
@return 对函数返回值做解释
@note 表示注解,暴露给源码阅读者的文档
@remark 表示评论,暴露给客户程序员的文档
@since 表示从那个版本起开始有了这个函数
@deprecated引起不推荐使用的警告
@see 表示交叉参考
函数的详细注释用@note代替详细注释,因为详细注释要空行隔开,容易忘记。
(4)成员注释
/**<或//<用来注释成员,放在成员后面,格式如下:
int var; /**< Detailed description after the member */
int var; ///< Brief description after the member
此语法对函数成员也适用。
(5)枚举类型注释
/** @brief Another enum, with inline docs */
enum AnotherEnum
{
V1, /**< value 1 */
V2/**< value 2 */
};
一般约定:
(1)每个.h和.cpp文件的头部,必须要有简要注释和详细注释,习惯用法如下:
/** @file
*@brief brief description.
* @author <list of authors>
* @date <date>
* @version <version number>
*
* detailed description for test.cpp
*/
(2)每个类的声明上方,必须要有简要注释和详细注释,习惯用法如下:
/**
* @class
* @brief brief description
*
* detailed description
*/
(3)全局变量和全局宏必须要有注释。
如果注释较短,则可以在上方用
/** @brief some brief description */或右方用
///< some brief description。
进行简要注释。
(4)任何函数都必须要有简要注释和详细注释,习惯用法如下:
/**
* @brief brief description.
* @param <parameter-name> <parameter description>
* @exception <exception-object> <exception description>
* @return <description of the return value>
* @note <text>
* @remarks <remark text>
*/
对于类的函数成员,在头文件的定义处进行简要注释,放在上方:
class Test
{
public:
/** @brief brief description */
int m_test(int a);
}
而在实现出给出详细注释:
/**
* @param [IN] a a integer
* @exception none
* @return 0
* @note detailed description
* @remarks some remarks to be attentioned
*/
int Test::m_test(int a)
{
Return 0;
}
纯虚函数由于没有实现则简要注释和详细注释不需分开。
对于类的数据成员,只在头文件的定义处进行简要注释,不要详细注释。可以在上方用/** @brief some brief description */或右方用///< some brief description。
(5)每个枚举定义必须添加注释,格式如下:
/** Another enum, with inline docs */
enum AnotherEnum
{
V1, //< value 1
V2//< value 2
};
下面是一个简单的例子,完全符合约定:
/** @file
* @brief a brief description for the file.
* @author soulmachine
* @date 2008/07/02
* @version 0.1
*
* detailed description for test.cpp
*/
/** @brief global function, no details
* @note some details about global function
*/
void global_test();
/** @class Test test.h "inc/test.h"
* @brief A test class.
*
* A more elaborate class description.
*/
class Test
{
public:
/** @brief A enum, with inline docs */
enum TEnum {
TVal1, /**< enum value TVal1. */
TVal2, /**< enum value TVal2. */
TVal3/**< enum value TVal3. */
}
//这里Doxygen对enumPtr的处理有点问题
*enumPtr, ///< enum pointer.
enumVar;///< enum variable.
/** @brief A constructor. */
Test();
/** @brief A destructor. */
~Test();
/** @brief a normal member taking two arguments and returning an integer value. */
int testMe(int a,const char *s);
/** @brief A pure virtual member.
* @param [IN] c1 the first argument.
* @param [IN] c2 the second argument.
* @see testMe()
*/
virtual void testMeToo(char c1,char c2) = 0;
int publicVar;//< a public variable.
/** @brief a function variable, note Details. */
int (*handler)(int a,int b);
/** @brief brief before delaration */
int m_func(int a);
};
/** A more elaborate description of the constructor. */
Test::Test()
{
}
/** A more elaborate description of the destructor. */
Test::~Test()
{
}
/**
* @param [IN] a an integer argument.
* @param [IN] s a constant character pointer.
* @return The test results
* @note Details.
* @par
* Another detail.
* @see Test()
* @see ~Test()
* @see testMeToo()
* @see publicVar()
*/
int Test::testMe(int a,const char *s)
{
return 0;
}
/**
* @param [IN] a a interger
* @return 0
* @note detailed description
* @remarks remarks,important
* @since 1.0
* @see testMeToo
*/
int Test::m_func(int a)
{
return 0;
}
参考资料:
相关推荐
Doxygen 快速 入门 教程。。绝对一学就会。。。
代码文档工具Doxygen快速入门V1.00_20120704(ZLG模板)
(1)文件头注释/** @file [file-name] *@brief brief description* @author <list of author
doxygen使用说明,标准注释说明及快速入门 svn说明
Doxygen进行C++归档快速入门,教程见博客...包含自己整理的Doxygen归档快速入门教程一份,doxygen1.8.4安装文件,doxygen中文手册,graphviz2.30.1绘图安装文件和HtmlHelpWorkShop安装文件HHWorkshop。
如果你实在想保留金典的散落Makefile风格,MakeDoxygen也可以满足你,这两篇文章会给你启示、2 怎样用到你的工程在决定使用MakeDoxygen前,先验证你的环境是否符合了解MakeDoxygen工作方式快速入门最后看看...
使用CMake构建RAMSES-GPU的快速入门(推荐) 可以使用env变量CUDAFLAGS将默认的CUDA编译标志传递给cmake,或在配置命令行上直接设置CMAKE_CUDA_FLAGS(请参见下文)。 git克隆 cd ramsesGPU; mkdir构建 cmake -DUSE_...
C ++入门模板存储库的精选列表,可用于快速启动新的C ++项目。 :启动您的C ++! 使用CMake,CI,代码覆盖率,clang格式,可重现的依赖性管理等现代C ++项目的模板 :清洁C ++项目供您使用。 功能:现代CMake,CPack...
快速开始快速入门使用最新Linux,例如Ubuntu。 sudo apt install g++-8 cmake make libeigen3-dev libopenmpi-dev doxygen graphviz libgnuplot-iostream-dev 从Paradiseo目录: mkdir build ; cd build ; cmake -D ...
这是快速入门教程,其中包含一些有关如何使用上述c ++绑定的示例。 提供了更精确的信息。 使用Nix 还提供了nix实用程序,以便在本地安装/构建free_fdb以便进行本地开发。 CI使用它。 nix-build . -A ffdb 如果要...
概述 Cotila(共mpile- TI我升inear一个lgebra)是仅头-库,提供了一组线性代数函数在C ++中用于在编译时期间使用。 Cotila中可用的所有...快速入门指南 要使用Cotila,您所需要做的就是#include <cotila/cotila.
入门这是编译此存储库中给出的示例的快速方法。1.安装Pico SDK 首先,确保正确安装和配置了Pico SDK: # Install dependenciessudo apt install cmake gcc-arm-none-eabi doxygen libnewlib-arm-none-eabigit clone ...
它被设计为快速且高度可扩展的,并由志愿者贡献者通过Internet开发。 该任务旨在使软件易于理解,修改,审核和扩展。 Matrix旨在让您控制自己的交流; 构造是关于让您控制Matrix。 您的隐私和安全问题。 我们鼓励...
快速入门:设置 下载工具包(例如,通过单击“克隆或下载”按钮) 将其解压缩到适当的目录(例如C:\ toolkits \ ivis-master \ ivis \ InstallIvis.m) 运行InstallIvis.m(这可能会提示您安装所有必需的第三方工具...
matlab一次多重式拟合代码PCSC数据近似值2019 第5组:龙玉轩,张一婷 该项目致力于C ++中基本数据拟合算法的...快速入门 输入参数在目录core / config的配置文件中定义。 此文件夹core / config中已经提供了一个示例
iPregel,轻巧但快速 目录 输入图 历史 刊物 什么是iPregel? 简而言之, iPregel是一个共享内存框架,用于使用内存中执行的顶点为中心的图形处理。 具体来说,它是用C编写的,与OpenMP并行执行,在编写时总共不到...
TinyXML被设计得容易快速上手。它只有两个头文件和四个cpp文件。只需要把它们简单地加到你的项目中就行了。有一个例子文件——xmltest.cpp来引导你该怎么做。 TinyXML以Zlib许可来发布,所以你可以在开源或者商业...