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-doc1.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 = 0OUTPUT_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 ＝ ALL3.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 Generator
Doxygen Documentation Generator – Visual Studio Marketplace
给出了适配过程显示方式和对应的插件需要的配置命令。