Doxygen是一个开源跨平台的蕾西JavaDoc风格描述的文档系统,其可以通过一套归档源文件生成HTML/LATEX/RTF格式参考手册。官网:Doxygen: Doxygen。
使用Doxygen主要包含三项内容:1. 在代码中添加doxygen规则注释;2. 生成doxygen配置文档doxyfile,并对配置文件根据自己需求配置;graphviz的dot布局可视化配置,生成可视化调用关系图并发布。Doxygen工作过程中一般配合doxyWizard和graphviz工具一起使用。doxyWizard工具主要是用来通过图形的方式配置Doxygen用到的配置文件,并通过手动执行按钮执行文档生成过程。Graphviz是一种开源的将结构化信息展示成抽象图和网络的工具,配合其可以生成漂亮的类图文档。doxygen主要优点:
1. 注释紧跟代码,一条命令生成响应SDK,快捷、及时更新,容易维护。
2. 加上dot之后,函数关系、类关系等更加明确,有利于理解代码。
3. 输出格式丰富,适合各种形式发布。
4. 不同Doxyfile输出不同内容,适合对内对外发布。
1. Ubuntu18.04软件环境
1.1. 软件安装
Doxygen/DoxyWizard/graphviz配套工具安装。
sudo apt install doxygen
sudo apt install doxygen-gui
sudo apt install graphviz graphviz-doc
1.2. 配置Doxygen
Doxygen配置方式有两种,可以直接通过doxygen file配置,也可以通过GUI配置界面配置。我们这里只针对配置文件配置进行说明。
doxygen -s -g doxyfile --------------简化版的doxyfile,没有很多注释信息。
doxygen -g doxyfile
配置文件详细配置说明,需要注意的主要有
#---------------------------------------------------------------------------
# Project related configuration options
#---------------------------------------------------------------------------
DOXYFILE_ENCODING = UTF-8
PROJECT_NAME = "My Project" # 项目名称,将作为于所生成的程序文档首页标题
PROJECT_NUMBER = "1.0.0" # 文档版本号,对应项目版本号,如svn所生成的项目版本号
PROJECT_BRIEF =
PROJECT_LOGO =
OUTPUT_DIRECTORY = doc # 程序文档输出目录
CREATE_SUBDIRS = YES
ALLOW_UNICODE_NAMES = NO
OUTPUT_LANGUAGE = English
BRIEF_MEMBER_DESC = YES
REPEAT_BRIEF = YES
ABBREVIATE_BRIEF = "The $name class" \
"The $name widget" \
"The $name file" \
is \
provides \
specifies \
contains \
represents \
a \
an \
the
ALWAYS_DETAILED_SEC = NO
INLINE_INHERITED_MEMB = NO
FULL_PATH_NAMES = NO
STRIP_FROM_PATH =
STRIP_FROM_INC_PATH =
SHORT_NAMES = NO
JAVADOC_AUTOBRIEF = YES
QT_AUTOBRIEF = NO
MULTILINE_CPP_IS_BRIEF = NO
INHERIT_DOCS = YES
SEPARATE_MEMBER_PAGES = NO
TAB_SIZE = 4
ALIASES =
TCL_SUBST =
OPTIMIZE_OUTPUT_FOR_C = NO
OPTIMIZE_OUTPUT_JAVA = NO
OPTIMIZE_FOR_FORTRAN = NO
OPTIMIZE_OUTPUT_VHDL = NO
EXTENSION_MAPPING =
MARKDOWN_SUPPORT = YES
TOC_INCLUDE_HEADINGS = 0
AUTOLINK_SUPPORT = YES
BUILTIN_STL_SUPPORT = NO
CPP_CLI_SUPPORT = NO
SIP_SUPPORT = NO
IDL_PROPERTY_SUPPORT = YES
DISTRIBUTE_GROUP_DOC = NO
GROUP_NESTED_COMPOUNDS = NO
SUBGROUPING = YES
INLINE_GROUPED_CLASSES = NO
INLINE_SIMPLE_STRUCTS = NO
TYPEDEF_HIDES_STRUCT = NO
LOOKUP_CACHE_SIZE = 0
OUTPUT_LANGUAGE = 文档的语言,如果是中文就设成Chinese
FILE_PATTERNS = 如果是C/C++的,就设置为
FILE_PATTERNS = *.c \
*.cc \
*.cxx \
*.cpp \
*.c++ \
*.h \
*.hxx \
*.hpp \
JAVADOC_AUTOBRIEF = 一般设置为YES
DOXYFILE_ENCODING = DoxyFile文件本身的编码格式,用UTF-8不带BOM
INPUT = 源文件的路径,一般DoxyFile也放这个路径下
INPUT_ENCODING = 源文件的编码,一般用UTF-8不带BOM
RECURSIVE = 一般设置为YES,这样可以递归处理源文件子目录
EXCLUDE_PATTERNS = 用来设置忽略子目录的。就是不把某目录,或者文件,当作输入文件,不想文档化的东西可以包含进来
1 EXCLUDE_PATTERNS = */snmp++/* \ 2 */Debug/* \ 3 */ipch/* \
比如以上是VS系列的东西,Debug,和ipch,SNMP++里面的东西我不想文档化。
INLINE_SOURCES = 文档内嵌代码接口实现,一般我设置为YES。如果公开给客户,需要关闭吧,设置为NO
STRIP_CODE_COMMENTS = 一般设置为YES,忽略非特殊格式的注释,就是普通注释
GENERATE_HTML = 设置为YES,如果需要要生成html格式的
HTML_OUTPUT = html
HTML_FILE_EXTENSION = .html html格式的文件后缀
一般以下几个变量我都会设置为YES,调用关系图和包含关系图等。
INCLUDE_GRAPH = YES
INCLUDED_BY_GRAPH = YES
CALL_GRAPH = YES
CALLER_GRAPH = YES
GRAPHICAL_HIERARCHY = YES
DIRECTORY_GRAPH = YES
# 程序文档语言环境
OUTPUT_LANGUAGE = Chinese
# 只对头文件中的文档化信息生成程序文档
FILE_PATTERNS =
# 递归遍历当前目录的子目录,寻找被文档化的程序源文件
RECURSIVE = YES
# 如果是制作 C 程序文档,该选项必须设为 YES,否则默认生成 C++ 文档格式
OPTIMIZE_OUTPUT_FOR_C = YES
#提取信息,包含类的私有数据成员和静态成员
EXTRACT_ALL = yes
EXTRACT_PRIVATE = yes
EXTRACT_STATIC = yes
# 对于使用 typedef 定义的结构体、枚举、联合等数据类型,只按照 typedef 定义的类型名进行文档化
TYPEDEF_HIDES_STRUCT = YES
# 在 C++ 程序文档中,该值可以设置为 NO,而在 C 程序文档中,由于 C 语言没有所谓的域/名字空间这样的概念,所以此处设置为 YES
HIDE_SCOPE_NAMES = YES
# 让 doxygen 静悄悄地为你生成文档,只有出现警告或错误时,才在终端输出提示信息
QUIET = YES
# 递归遍历示例程序目录的子目录,寻找被文档化的程序源文件
EXAMPLE_RECURSIVE = YES
# 允许程序文档中显示本文档化的函数相互调用关系
REFERENCED_BY_RELATION = YES
REFERENCES_RELATION = YES
REFERENCES_LINK_SOURCE = YES
# 不生成 latex 格式的程序文档
GENERATE_LATEX = NO
# 在程序文档中允许以图例形式显示函数调用关系,前提是你已经安装了 graphviz 软件包
HAVE_DOT = YES
CALL_GRAPH = YES
CALLER_GRAPH = YES
#在最后生成的文档中,把所有的源代码包含在其中
SOURCE BROWSER = YES
$这会在HTML文档中,添加一个侧边栏,并以树状结构显示包、类、接口等的关系
GENERATE TREEVIEW = ALL
3.Graphviz;
#---------------------------------------------------------------------------
# Configuration options related to the dot tool
#---------------------------------------------------------------------------
CLASS_DIAGRAMS = YES
MSCGEN_PATH =
DIA_PATH =
HIDE_UNDOC_RELATIONS = YES
HAVE_DOT = YES # 打开dot功能。
DOT_NUM_THREADS = 0
DOT_FONTNAME = Helvetica # 设置dot功能的字体和大小。
DOT_FONTSIZE = 10
DOT_FONTPATH =
CLASS_GRAPH = YES # 类等关系图。
COLLABORATION_GRAPH = YES
GROUP_GRAPHS = YES
UML_LOOK = NO
UML_LIMIT_NUM_FIELDS = 10
TEMPLATE_RELATIONS = NO
INCLUDE_GRAPH = YES # include关系图。
INCLUDED_BY_GRAPH = YES
CALL_GRAPH = YES # 调用和被调用关系图。
CALLER_GRAPH = YES
GRAPHICAL_HIERARCHY = YES
DIRECTORY_GRAPH = YES
DOT_IMAGE_FORMAT = png # dot输出的图像格式。
INTERACTIVE_SVG = NO
DOT_PATH = /usr/bin/dot # 系统dot路径,which dot确定
DOTFILE_DIRS =
MSCFILE_DIRS =
DIAFILE_DIRS =
PLANTUML_JAR_PATH =
PLANTUML_INCLUDE_PATH =
DOT_GRAPH_MAX_NODES = 50
MAX_DOT_GRAPH_DEPTH = 0
DOT_TRANSPARENT = NO
DOT_MULTI_TARGETS = NO
GENERATE_LEGEND = YES
DOT_CLEANUP = YES
由于使用到了Graphviz,所以要设置Dot选项,勾选HAVE_DOT,也就是配置其为YES。并设置DOT_PATH为Graphviz的bin目录。(注意:MAC的Graphviz的bin目录不在安装包内,一般是在/usr/local/bin/,实在找不到就到终端用ls一层一层的查找)。对于Ubuntu环境通过which dot命令查看其可执行文件位置。
另外,若Doxygen出现中文乱码问题,需要修改设置如下:
DOXYFILE_ENCODING:UTF-8
OUTPUT_LANGUAGE:Chinese
INPUT_ENCODING:GB2312
这样生就可以正确生成含有中文的文档了。
2. C++类型代码注释范例
Doxygen需要对特定格式的注释进行识别,在工程中要想使用这个工具就必须按照其要求的格式进行代码注释。C++中需要关注的代码主要包含类、成员变量、成员函数、函数句柄、结构体。doxygen规范主要掌握如下几点,对应的实例下图:
- 前置单行注释,以“///”开头;
- 后置单行注释,以“///<”开头,紧跟代码后面;
- 段落注释,以“/**”开始,以“*/”结束。
/**
* 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);
};
如上的代码注释结构是Javadoc风格,如果需要正常解析需要把配置文件JAVADOC_AUTOBRIEF设置成YES。
3. vscode开发环境
在vscode开发环境中,我们希望能够通过插件类辅助我们完成部分重复性的注释,这样可以大大提高开发效率,同时降低不必要的开发错误。vscode插件Doxygen Documentation GeneratorDoxygen Documentation Generator - Visual Studio Marketplace给出了适配过程显示方式和对应的插件需要的配置命令。