Ubuntu 下使用 Doxygen
来源：互联网 发布：npm i node sass d 编辑：程序博客网 时间：2024/05/29 08:30
一、安装Doxygen:(官方网站:http://www.stack.nl/~dimitri/doxygen/)
sudoapt-get install doxygen doxygen-doc doxygen-guigraphviz
注:如果要生成 png 格式的图片,必须安装 Graphviz 软件。
出现如下提示信息的话,则就不要安 doxygen-gui 了:
现在没有可用的软件包 doxygen-gui，但是它被其它的软件包引用了。
E: 软件包 doxygen-gui 还没有可供安装的候选者
sudoapt-get install doxygen doxygen-doc graphviz
二、Doxygen的工作过程可分为三个步骤:
1. 使用 "doxygen -g" 命令在当前目录下生成名为 Doxygen 的配置文件模板;
注:默认生成的配置文件名为 "Doxyfile",
也可以采用 "doxygen -g 指定文件名" 命令格式指定所生成的配置文件名。
如无特殊需要,采用默认的配置文件名即可。
如果对 Doxygen 各配置选项的意义有一定了解,
可以在生成配置文件的命令中添加 "-s" 选项,生成不含注释的配置文件,
如:doxygen -s -g。
2. 在程序源码中添加符合 Doxygen 可解析的注释格式;
3. 使用 Doxygen 解析源码,输出格式化文档。
可与指定名的模块的显示名不同。
3) @addtogroup 模块名(英文) [显示名(中文)] -->作为指定名的模块的成员,显示名为可选项,
必需与指定名的模块的显示名相同。
4) @name 显示名(中文) @{ 变量/宏 @} -->按用途分,以便理解全局变量/宏的用途
3. 函数信息:
1) @param 参数名 说明文字 --> 不建议使用这个
@param[in] 参数名 说明文字 --> 输入参数
@param[out] 参数名 说明文字 --> 输出参数
@param[in,out] 参数名 说明文字 --> 即输入又输出参数
2) @arg 参数/返回值 说明文字 --> 以列表形式说明参数取值意义
注:也可以用 - 或-# 来代替,建议此种方法,简单明了。
- 第一级
- 第二级
- 第三级
即相同开头的 - 或 -# 第二行比第一行缩进一个英文空格就变了第二级,依次类推。
- 开头的第一级为实心黑圆点;第二级为空心黑圆点;第三级以后为实心方块;
-# 开头的第一级为数字(1./2./3./...),
第二级为小写字母(a./b./c./...),
第三级为罗马数字(i./ii./iii./...),
第四级为大写字母(A./B./C./...)
3) @return 说明文字 --> 返回值说明
4) @retval 说明文字 --> 特定返回值说明
5) @note 说明文字 --> 注解,可以描述工作流程和注意事项
6) @par [段落标题] --> 开创新段落,一般与示例代码联用
7) @code --> 示例代码开始
8) @endcode --> 示例代码结束
9) @see 类/函数/变量/文件/URL --> 参见,
类名::函数名 或 ::函数名 可以变成超链接点击跳转到对应函数说明处
函数重载的情况下,要带上参数列表以及返回值
10) @deprecated 说明文字 -->过时列表,在相关页面有它专门一项,
注:只能在头文件(*.h)中使用,如果相同函数的实现文件与头文件中均有,
生成的文档中会有重复项,可以理解为维护者不关心这个接口是不是要过时。
11) @pre 说明文字 --> 前置条件
4. 提醒信息:
1) @brief 说明文字 --> 摘要,即当前文件/函数说明
2) @attention 说明文字 --> 注意
3) @bug 说明文字 --> 问题
4) @warning 说明文字 --> 警告
四、doxygen 的注释规则:
并非所有程序代码中的注释都会被 Doxygen 处理,必需依照正确的格式撰写,
Doxygen 可处理下面两种类型的注解,如下:
由于 Doxygen 认为注释是说明它下面的程序代码。
所以,如果注释要与前面的程序码在同一行内,则需用下面这种型式的注释:
注意,除**后多了一个<,其它的与 1_2 相同。
首先,我们先说明在 Doxygen 中对於类别或是函数注解的一个特定格 式。
上面这个例子要说的是,在 Doxygen 处理一个类定义或是函数定义之上的注释时:
会先判断第一行为简易说明,这个简易说明将一直到遇见一个空白行的出现或是遇到第一个 . 为止;
之后的注解将会被视为详细说明。
另一种比较清楚的方式是指定@brief 的指令,这将会明确的告诉 Doxygen 哪个是简易说明。
五、doxygen配置文件模板各项说明:
(注:以下内容为 doxygen -s -g 得到,中文注释均我手工添加,有中文注释的项较为重要)
# Doxyfile 1.6.1
#---------------------------------------------------------------------------
# Project related configuration options
#---------------------------------------------------------------------------
DOXYFILE_ENCODING = UTF-8
# 项目名称,将作为于所生成的程序文档首页标题,需要使用双引号括住
PROJECT_NAME = “Unnamed Project”
# 文档版本号,可对应于项目版本号,譬如 svn、cvs 所生成的项目版本号
PROJECT_NUMBER = “1.0.0”
# 程序文档输出目录,产生的文件会放在这个路径之下。
# 如果没有填这个路径,将会以当前所在路径来作为输出路径。
OUTPUT_DIRECTORY = doc/
CREATE_SUBDIRS = NO
# 程序文档语言环境,预设为 English。
# 1.2.16 版后,可以用 Chinese 输出简体中文,
# 也可以使用 Chinese-Traditional 来输出中文繁体的格式。
OUTPUT_LANGUAGE = Chinese
BRIEF_MEMBER_DESC = YES
REPEAT_BRIEF = YES
ABBREVIATE_BRIEF =
ALWAYS_DETAILED_SEC = NO
INLINE_INHERITED_MEMB = NO
FULL_PATH_NAMES = YES
STRIP_FROM_PATH =
STRIP_FROM_INC_PATH =
SHORT_NAMES = NO
JAVADOC_AUTOBRIEF = NO
QT_AUTOBRIEF = NO
MULTILINE_CPP_IS_BRIEF = NO
INHERIT_DOCS = YES
SEPARATE_MEMBER_PAGES = NO
TAB_SIZE = 8
ALIASES =
# 如果是制作 C 程序文档,该选项必须设为 YES,否则默认生成 C++ 文档格式
OPTIMIZE_OUTPUT_FOR_C = YES
OPTIMIZE_OUTPUT_JAVA = NO
OPTIMIZE_FOR_FORTRAN = NO
OPTIMIZE_OUTPUT_VHDL = NO
EXTENSION_MAPPING =
BUILTIN_STL_SUPPORT = NO
CPP_CLI_SUPPORT = NO
SIP_SUPPORT = NO
IDL_PROPERTY_SUPPORT = YES
DISTRIBUTE_GROUP_DOC = NO
SUBGROUPING = YES
# 对于使用 typedef 定义的结构体、枚举、联合等数据类型,
# 只按照 typedef 定义的类型名进行文档化
TYPEDEF_HIDES_STRUCT = YES
SYMBOL_CACHE_SIZE = 0
#---------------------------------------------------------------------------
# Build related configuration options
#---------------------------------------------------------------------------
# 把这个标记设置为 Yes,即使各个类或函数没有文档,也要提取信息。
EXTRACT_ALL = YES
# 把这个标记设置为 Yes,文档就会包含类的私有数据成员。
EXTRACT_PRIVATE = YES
# 把这个标记设置为 Yes,文档就会包含文件的静态成员(函数和变量)。
EXTRACT_STATIC = YES
EXTRACT_LOCAL_CLASSES = YES
EXTRACT_LOCAL_METHODS = NO
EXTRACT_ANON_NSPACES = NO
HIDE_UNDOC_MEMBERS = NO
HIDE_UNDOC_CLASSES = NO
HIDE_FRIEND_COMPOUNDS = NO
HIDE_IN_BODY_DOCS = NO
INTERNAL_DOCS = NO
CASE_SENSE_NAMES = YES
# 在 C++ 程序文档中,该值可以设置为 NO,
# 而在 C 程序文档中,由于 C 语言没有所谓的域/名字空间这样的概念,所以此处设置为 YES。
HIDE_SCOPE_NAMES = YES
SHOW_INCLUDE_FILES = YES
INLINE_INFO = YES
SORT_MEMBER_DOCS = YES
SORT_BRIEF_DOCS = NO
SORT_MEMBERS_CTORS_1ST = NO
SORT_GROUP_NAMES = NO
SORT_BY_SCOPE_NAME = NO
GENERATE_TODOLIST = YES
GENERATE_TESTLIST = YES
GENERATE_BUGLIST = YES
GENERATE_DEPRECATEDLIST= YES
ENABLED_SECTIONS =
MAX_INITIALIZER_LINES = 30
SHOW_USED_FILES = YES
SHOW_DIRECTORIES = NO
SHOW_FILES = YES
SHOW_NAMESPACES = YES
FILE_VERSION_FILTER =
LAYOUT_FILE =
#---------------------------------------------------------------------------
# configuration options related to warning and progressmessages
#---------------------------------------------------------------------------
# 让 doxygen 静悄悄地为你生成文档,只有出现警告或错误时,才在终端输出提示信息。
QUIET = YES
WARNINGS = YES
WARN_IF_UNDOCUMENTED = YES
WARN_IF_DOC_ERROR = YES
WARN_NO_PARAMDOC = NO
WARN_FORMAT = "$file:$line: $text"
WARN_LOGFILE =
#---------------------------------------------------------------------------
# configuration options related to the input files
#---------------------------------------------------------------------------
# 这个标记创建一个以空格分隔的所有目录的列表,
# 这个列表包含需要生成文档的 C/C++ 源代码文件和头文件,可以不设定,即为当前目录!
INPUT =
INPUT_ENCODING = UTF-8
# 在默认情况下,doxygen 会搜索具有典型 C/C++ 扩展名的文件,
# 比如 .c、.cc、.cpp、.h 和 .hpp 。
# 可以使用如下形式的列表方式,指定要处理的文件。
# 注:文件类型后有空格然后是右斜杠然后回车,每一个文件类均独自一行!
# FILE_PATTERNS = *.h \
*.c \
*.cpp
FILE_PATTERNS =
# 递归遍历由 INPUT 所指定的目录及其所有子目录,寻找由 FILE_PATTERNS 指定的要被文档化的文件
RECURSIVE = YES
# 如果您有特定文件或目录,不希望经过 Doxygen 处理,那你可在这指出,没有就不指出。
# 例如:EXCLUDE = /home/user1/src_root /home/user1/test
EXCLUDE =
EXCLUDE_SYMLINKS = NO
# 类似于 FILE_PATTERNS 的用法,只是这个是供 EXCLUDE 所使用。
EXCLUDE_PATTERNS =
EXCLUDE_SYMBOLS =
# 示例程序目录
EXAMPLE_PATH = example/
# 示例程序的头文件(.h) 与实现文件(.c 或 .cpp)都作为程序文档化对象,
# 可以使用如下形式的列表方式,指定要处理的文件。
# 注:文件类型后有空格然后是右斜杠然后回车,每一个文件类均独自一行!
EXAMPLE_PATTERNS = *.h \
*.c \
sudoapt-get install doxygen doxygen-doc doxygen-guigraphviz
注:如果要生成 png 格式的图片,必须安装 Graphviz 软件。
出现如下提示信息的话,则就不要安 doxygen-gui 了:
现在没有可用的软件包 doxygen-gui，但是它被其它的软件包引用了。
E: 软件包 doxygen-gui 还没有可供安装的候选者
sudoapt-get install doxygen doxygen-doc graphviz
二、Doxygen的工作过程可分为三个步骤:
1. 使用 "doxygen -g" 命令在当前目录下生成名为 Doxygen 的配置文件模板;
注:默认生成的配置文件名为 "Doxyfile",
也可以采用 "doxygen -g 指定文件名" 命令格式指定所生成的配置文件名。
如无特殊需要,采用默认的配置文件名即可。
如果对 Doxygen 各配置选项的意义有一定了解,
可以在生成配置文件的命令中添加 "-s" 选项,生成不含注释的配置文件,
如:doxygen -s -g。
2. 在程序源码中添加符合 Doxygen 可解析的注释格式;
3. 使用 Doxygen 解析源码,输出格式化文档。
仅仅需要 Doxygen 完成以下流程即可满足我的需求:
在 Doxygen 手册页上可以看到一份很详细的 Doxgen工作流程图
(http://www.stack.nl/~dimitri/doxygen/starting.html)
三、Doxygen常用标签命令关键字:
1. 文件信息:
1) @file 文件名(遵守文件命名规则) --> 文件声明，即当前文件名
2) @author 作者名 --> 作者
3) @version 版本号 --> 版本号
4) @todo 说明文字 --> TODO 列表，在相关页面有它专门一项
注:只能在实现文件(*.c/*.cpp)中使用，
如果相同函数的实现文件与头文件中均有,生成的文档中会有重复项，
可以理解为调用者不应知道实现流程。
5) @date 日期时间 --> 说明文件生成的日期时间
6) @section 章节标题 --> @section LICENSE 版权许可@section DESCRIPTION 描述
2. 模块信息:
1) @defgroup 模块名(英文) 显示名(中文) @{ 类/函数/变量/宏/...@}--> 定义模块
2) @ingroup 模块名(英文) [显示名(中文)]-->作为指定名的模块的子模块,显示名为可选项,
3) @addtogroup 模块名(英文) [显示名(中文)] -->作为指定名的模块的成员,显示名为可选项,
4) @name 显示名(中文) @{ 变量/宏 @} -->按用途分,以便理解全局变量/宏的用途
3. 函数信息:
1) @param 参数名 说明文字 --> 不建议使用这个
2) @arg 参数/返回值 说明文字 --> 以列表形式说明参数取值意义
3) @return 说明文字 --> 返回值说明
4) @retval 说明文字 --> 特定返回值说明
5) @note 说明文字 --> 注解,可以描述工作流程和注意事项
6) @par [段落标题] --> 开创新段落,一般与示例代码联用
7) @code --> 示例代码开始
8) @endcode --> 示例代码结束
9) @see 类/函数/变量/文件/URL --> 参见,
4. 提醒信息:
1) @brief 说明文字 --> 摘要,即当前文件/函数说明
2) @attention 说明文字 --> 注意
3) @bug 说明文字 --> 问题
4) @warning 说明文字 --> 警告
四、doxygen 的注释规则:
并非所有程序代码中的注释都会被 Doxygen 处理,必需依照正确的格式撰写,
Doxygen 可处理下面两种类型的注解,如下:
由于 Doxygen 认为注释是说明它下面的程序代码。
所以,如果注释要与前面的程序码在同一行内,则需用下面这种型式的注释:
注意,除**后多了一个<,其它的与 1_2 相同。
首先,我们先说明在 Doxygen 中对於类别或是函数注解的一个特定格 式。
上面这个例子要说的是,在 Doxygen 处理一个类定义或是函数定义之上的注释时:
会先判断第一行为简易说明,这个简易说明将一直到遇见一个空白行的出现或是遇到第一个 . 为止;
之后的注解将会被视为详细说明。
另一种比较清楚的方式是指定@brief 的指令,这将会明确的告诉 Doxygen 哪个是简易说明。
五、doxygen配置文件模板各项说明:
(注:以下内容为 doxygen -s -g 得到,中文注释均我手工添加,有中文注释的项较为重要)
# Doxyfile 1.6.1
#---------------------------------------------------------------------------
# Project related configuration options
#---------------------------------------------------------------------------
DOXYFILE_ENCODING = UTF-8
# 项目名称,将作为于所生成的程序文档首页标题,需要使用双引号括住
PROJECT_NAME = “Unnamed Project”
# 文档版本号,可对应于项目版本号,譬如 svn、cvs 所生成的项目版本号
PROJECT_NUMBER = “1.0.0”
# 程序文档输出目录,产生的文件会放在这个路径之下。
# 如果没有填这个路径,将会以当前所在路径来作为输出路径。
OUTPUT_DIRECTORY = doc/
CREATE_SUBDIRS = NO
# 程序文档语言环境,预设为 English。
# 1.2.16 版后,可以用 Chinese 输出简体中文,
# 也可以使用 Chinese-Traditional 来输出中文繁体的格式。
OUTPUT_LANGUAGE = Chinese
BRIEF_MEMBER_DESC = YES
REPEAT_BRIEF = YES
ABBREVIATE_BRIEF =
ALWAYS_DETAILED_SEC = NO
INLINE_INHERITED_MEMB = NO
FULL_PATH_NAMES = YES
STRIP_FROM_PATH =
STRIP_FROM_INC_PATH =
SHORT_NAMES = NO
JAVADOC_AUTOBRIEF = NO
QT_AUTOBRIEF = NO
MULTILINE_CPP_IS_BRIEF = NO
INHERIT_DOCS = YES
SEPARATE_MEMBER_PAGES = NO
TAB_SIZE = 8
ALIASES =
# 如果是制作 C 程序文档,该选项必须设为 YES,否则默认生成 C++ 文档格式
OPTIMIZE_OUTPUT_FOR_C = YES
OPTIMIZE_OUTPUT_JAVA = NO
OPTIMIZE_FOR_FORTRAN = NO
OPTIMIZE_OUTPUT_VHDL = NO
EXTENSION_MAPPING =
BUILTIN_STL_SUPPORT = NO
CPP_CLI_SUPPORT = NO
SIP_SUPPORT = NO
IDL_PROPERTY_SUPPORT = YES
DISTRIBUTE_GROUP_DOC = NO
SUBGROUPING = YES
# 对于使用 typedef 定义的结构体、枚举、联合等数据类型,
# 只按照 typedef 定义的类型名进行文档化
TYPEDEF_HIDES_STRUCT = YES
SYMBOL_CACHE_SIZE = 0
#---------------------------------------------------------------------------
# Build related configuration options
#---------------------------------------------------------------------------
# 把这个标记设置为 Yes,即使各个类或函数没有文档,也要提取信息。
EXTRACT_ALL = YES
# 把这个标记设置为 Yes,文档就会包含类的私有数据成员。
EXTRACT_PRIVATE = YES
# 把这个标记设置为 Yes,文档就会包含文件的静态成员(函数和变量)。
EXTRACT_STATIC = YES
EXTRACT_LOCAL_CLASSES = YES
EXTRACT_LOCAL_METHODS = NO
EXTRACT_ANON_NSPACES = NO
HIDE_UNDOC_MEMBERS = NO
HIDE_UNDOC_CLASSES = NO
HIDE_FRIEND_COMPOUNDS = NO
HIDE_IN_BODY_DOCS = NO
INTERNAL_DOCS = NO
CASE_SENSE_NAMES = YES
# 在 C++ 程序文档中,该值可以设置为 NO,
# 而在 C 程序文档中,由于 C 语言没有所谓的域/名字空间这样的概念,所以此处设置为 YES。
HIDE_SCOPE_NAMES = YES
SHOW_INCLUDE_FILES = YES
INLINE_INFO = YES
SORT_MEMBER_DOCS = YES
SORT_BRIEF_DOCS = NO
SORT_MEMBERS_CTORS_1ST = NO
SORT_GROUP_NAMES = NO
SORT_BY_SCOPE_NAME = NO
GENERATE_TODOLIST = YES
GENERATE_TESTLIST = YES
GENERATE_BUGLIST = YES
GENERATE_DEPRECATEDLIST= YES
ENABLED_SECTIONS =
MAX_INITIALIZER_LINES = 30
SHOW_USED_FILES = YES
SHOW_DIRECTORIES = NO
SHOW_FILES = YES
SHOW_NAMESPACES = YES
FILE_VERSION_FILTER =
LAYOUT_FILE =
#---------------------------------------------------------------------------
# configuration options related to warning and progressmessages
#---------------------------------------------------------------------------
# 让 doxygen 静悄悄地为你生成文档,只有出现警告或错误时,才在终端输出提示信息。
QUIET = YES
WARNINGS = YES
WARN_IF_UNDOCUMENTED = YES
WARN_IF_DOC_ERROR = YES
WARN_NO_PARAMDOC = NO
WARN_FORMAT = "$file:$line: $text"
WARN_LOGFILE =
#---------------------------------------------------------------------------
# configuration options related to the input files
#---------------------------------------------------------------------------
# 这个标记创建一个以空格分隔的所有目录的列表,
# 这个列表包含需要生成文档的 C/C++ 源代码文件和头文件,可以不设定,即为当前目录!
INPUT =
INPUT_ENCODING = UTF-8
# 在默认情况下,doxygen 会搜索具有典型 C/C++ 扩展名的文件,
# 比如 .c、.cc、.cpp、.h 和 .hpp 。
# 可以使用如下形式的列表方式,指定要处理的文件。
# 注:文件类型后有空格然后是右斜杠然后回车,每一个文件类均独自一行!
# FILE_PATTERNS = *.h \
FILE_PATTERNS =
# 递归遍历由 INPUT 所指定的目录及其所有子目录,寻找由 FILE_PATTERNS 指定的要被文档化的文件
RECURSIVE = YES
# 如果您有特定文件或目录,不希望经过 Doxygen 处理,那你可在这指出,没有就不指出。
# 例如:EXCLUDE = /home/user1/src_root /home/user1/test
EXCLUDE =
EXCLUDE_SYMLINKS = NO
# 类似于 FILE_PATTERNS 的用法,只是这个是供 EXCLUDE 所使用。
EXCLUDE_PATTERNS =
EXCLUDE_SYMBOLS =
# 示例程序目录
EXAMPLE_PATH = example/
# 示例程序的头文件(.h) 与实现文件(.c 或 .cpp)都作为程序文档化对象,
# 可以使用如下形式的列表方式,指定要处理的文件。
# 注:文件类型后有空格然后是右斜杠然后回车,每一个文件类均独自一行!
EXAMPLE_PATTERNS = *.h \