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 可处理下面两种类型的注解,如下:
![Ubuntu <wbr>下使用 <wbr>Doxygen Ubuntu <wbr>下使用 <wbr>Doxygen](https://i-blog.csdnimg.cn/blog_migrate/715aa76a4c29d7eaba6ca5ead0de0791.jpeg)
由于 Doxygen 认为注释是说明它下面的程序代码。
所以,如果注释要与前面的程序码在同一行内,则需用下面这种型式的注释:
![Ubuntu <wbr>下使用 <wbr>Doxygen Ubuntu <wbr>下使用 <wbr>Doxygen](https://i-blog.csdnimg.cn/blog_migrate/88fecd4ca2a05d97f6407a427ad469e6.jpeg)
注意,除**后多了一个<,其它的与 1_2 相同。
首先,我们先说明在 Doxygen 中对於类别或是函数注解的一个特定格 式。
![Ubuntu <wbr>下使用 <wbr>Doxygen Ubuntu <wbr>下使用 <wbr>Doxygen](https://i-blog.csdnimg.cn/blog_migrate/f8c5c0eb143e944f293da6570713e57b.jpeg)
上面这个例子要说的是,在 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 \
# 递归遍历示例程序目录的子目录,寻找被文档化的程序源文件。
EXAMPLE_RECURSIVE = YES
IMAGE_PATH =
INPUT_FILTER =
FILTER_PATTERNS =
FILTER_SOURCE_FILES = NO
#---------------------------------------------------------------------------
# configuration options related to source browsing
#---------------------------------------------------------------------------
# 如果设定为 YES,则 Doxygen 会产生出原始档案的列表,以供查阅,默认为 NO。
SOURCE_BROWSER = NO
# 如果设定为 YES ,则程式码也会被嵌入於说明文件中,默认为 NO。
INLINE_SOURCES = NO
STRIP_CODE_COMMENTS = YES
# 允许程序文档中显示本文档化的函数相互调用关系
REFERENCED_BY_RELATION = YES
# 允许程序文档中显示本文档化的函数相互调用关系
REFERENCES_RELATION = YES
# 允许程序文档中显示本文档化的函数相互调用关系
REFERENCES_LINK_SOURCE = YES
USE_HTAGS = NO
VERBATIM_HEADERS = YES
#---------------------------------------------------------------------------
# configuration options related to the alphabetical classindex
#---------------------------------------------------------------------------
# 如果设定为 YES,则一个依照字母排序的列表会加入在产生的文件中,默认为 NO。
ALPHABETICAL_INDEX = NO
COLS_IN_ALPHA_INDEX = 5
IGNORE_PREFIX =
#---------------------------------------------------------------------------
# configuration options related to the HTML output
#---------------------------------------------------------------------------
# 若设定为 YES,就会产生 HTML 版本的说明文件。HTML 文件是 Doxygen 预设产生的格式之一。
GENERATE_HTML = YES
# HTML 文件的输出目录。
# 这是一个相对路径,所以实际的路径为 OUTPUT_DIRECTORY 加上 HTML_OUTPUT。
# 这个设定预设为 html。
HTML_OUTPUT = html
# HTML 文件的扩展名。预设为.html。
HTML_FILE_EXTENSION = .html
# 要使用在每一页 HTML 文件中的页眉。如果没有指定,Doxygen 会使用自己预设的页眉。
HTML_HEADER =
# 要使用在每一页 HTML 文件中的页脚。如果没有指定,Doxygen 会使用自己预设的页脚。
HTML_FOOTER =
# 您可给定一个 CSS 的设定,让 HTML 的输出结果更完美。
HTML_STYLESHEET =
HTML_ALIGN_MEMBERS = YES
HTML_DYNAMIC_SECTIONS = NO
GENERATE_DOCSET = NO
DOCSET_FEEDNAME = "Doxygen generated docs"
DOCSET_BUNDLE_ID = org.doxygen.Project
# 如设定为 YES,Doxygen 会产生一个索引档。
# 这个索引档在您需要制作 windows 上的 HTML 格式的 HELP 档案时会用的上。
GENERATE_HTMLHELP = NO
CHM_FILE =
HHC_LOCATION =
GENERATE_CHI = NO
CHM_INDEX_ENCODING =
BINARY_TOC = NO
TOC_EXPAND = NO
GENERATE_QHP = NO
QCH_FILE =
QHP_NAMESPACE =
QHP_VIRTUAL_FOLDER = doc
QHP_CUST_FILTER_NAME =
QHP_CUST_FILTER_ATTRS =
QHP_SECT_FILTER_ATTRS =
QHG_LOCATION =
DISABLE_INDEX = NO
ENUM_VALUES_PER_LINE = 4
# 若设定为 YES,Doxygen 会帮您产生一个树状结构,在页面左侧,默认为 NO。
# 这个树状结构是以 JavaScript 所写成。所以需要新版的 Browser 才能正确显示。
GENERATE_TREEVIEW = YES
USE_INLINE_TREES = NO
# 用来设定树状结构在页面上的宽度,默认 250。
TREEVIEW_WIDTH = 250
FORMULA_FONTSIZE = 10
SEARCHENGINE = YES
#---------------------------------------------------------------------------
# configuration options related to the LaTeX output
#---------------------------------------------------------------------------
# 设定为 YES 时,会产生 LaTeX 的文件。
# 不过您的系统必需要有安装 LaTeX 的相关工具,默认为 NO。
GENERATE_LATEX = NO
# LaTeX 文件的输出目录,与 HTML_OUTPUT 用法相同,
# 一样是指在 OUTPUT_DIRECTORY 之下的路径。预设为 latex。
LATEX_OUTPUT = latex
# LaTeX 程式的命令名称及档案所在。预设为 latex。
LATEX_CMD_NAME = latex
MAKEINDEX_CMD_NAME = makeindex
COMPACT_LATEX = NO
PAPER_TYPE = a4wide
EXTRA_PACKAGES =
LATEX_HEADER =
PDF_HYPERLINKS = YES
USE_PDFLATEX = YES
LATEX_BATCHMODE = NO
LATEX_HIDE_INDICES = NO
LATEX_SOURCE_CODE = NO
#---------------------------------------------------------------------------
# configuration options related to the RTF output
#---------------------------------------------------------------------------
# 若设定为 YES ,则会产生 RTF 格式的说明文件,默认为 NO。
GENERATE_RTF = NO
# 与 HTML_OUTPUT 用法相同,用来指定 RTF 文件输出路径。默认为 rtf。
RTF_OUTPUT = rtf
COMPACT_RTF = NO
# 要想支持跨文档浏览把这个标记设置为 Yes。
RTF_HYPERLINKS = NO
RTF_STYLESHEET_FILE =
RTF_EXTENSIONS_FILE =
#---------------------------------------------------------------------------
# configuration options related to the man page output
#---------------------------------------------------------------------------
# 若设定为 YES ,则会产生 Unix Man Page 格式的说明文件,默认为 NO。
GENERATE_MAN = NO
# 与 HTML_OUTPUT 用法相同,用来指定 Man Page 的输出目录。预设为 man。
MAN_OUTPUT = man
MAN_EXTENSION = .3
MAN_LINKS = NO
#---------------------------------------------------------------------------
# configuration options related to the XML output
#---------------------------------------------------------------------------
# 若设定为 YES ,则会产生 XML 格式的说明文件,默认为 NO。
GENERATE_XML = NO
XML_OUTPUT = xml
XML_SCHEMA =
XML_DTD =
XML_PROGRAMLISTING = YES
#---------------------------------------------------------------------------
# configuration options for the AutoGen Definitions output
#---------------------------------------------------------------------------
GENERATE_AUTOGEN_DEF = NO
#---------------------------------------------------------------------------
# configuration options related to the Perl module output
#---------------------------------------------------------------------------
GENERATE_PERLMOD = NO
PERLMOD_LATEX = NO
PERLMOD_PRETTY = YES
PERLMOD_MAKEVAR_PREFIX =
#---------------------------------------------------------------------------
# Configuration options related to the preprocessor
#---------------------------------------------------------------------------
# 若设定为 YES ,则 Doxygen 会启动 C 的预处理器来处理源文件,默认为 YES。
ENABLE_PREPROCESSING = YES
# 为了执行宏展开,还应该把这个标记设置为 YES。
MACRO_EXPANSION = YES
# 把这个标记设置为 Yes,希望只展开特定的宏,
# 需要在<PREDEFINED> 或<EXPAND_AS_DEFINED> 标记中提供宏的。
EXPAND_ONLY_PREDEF = NO
SEARCH_INCLUDES = YES
INCLUDE_PATH =
INCLUDE_FILE_PATTERNS =
# 提供宏的名字。
# 就像用 -D 开关向 C++ 编译器传递预处理器定义一样,使用这个标记定义宏。
# 多个宏定义以右斜杠(\)分隔,空格右斜杠换行,每个宏定义独占一行,
# 如果不提供值,等于号后有一个空格即可,例如:。
# PREDEFINED = USE_ROPE= \
#
ALLOW_RANDOM_ACCESS=1
PREDEFINED =
# 提供宏的名字。
EXPAND_AS_DEFINED =
SKIP_FUNCTION_MACROS = YES
#---------------------------------------------------------------------------
# Configuration::additions related to external references
#---------------------------------------------------------------------------
TAGFILES =
GENERATE_TAGFILE =
ALLEXTERNALS = NO
EXTERNAL_GROUPS = YES
PERL_PATH = /usr/bin/perl
#---------------------------------------------------------------------------
# Configuration options related to the dot tool
#---------------------------------------------------------------------------
# 这个标记默认设置为 YES,生成继承层次结构图,默认为 YES。
CLASS_DIAGRAMS = YES
MSCGEN_PATH =
HIDE_UNDOC_RELATIONS = YES
# 在程序文档中允许以图例形式显示函数调用关系,前提是你已经安装了 graphviz 软件包
# 如果这个标记设置为 Yes,doxygen 就使用 dot 工具生成更强大的图形,
# 比如帮助理解类成员及其数据结构的协作图。
# 注意,如果这个标记设置为 Yes,CLASS_DIAGRAMS 标记就无效了。
HAVE_DOT = YES
DOT_FONTNAME = FreeSans
DOT_FONTSIZE = 10
DOT_FONTPATH =
# 如果 HAVE_DOT 标记和这个标记同时设置为 YES,就使用 dot 生成继承层次结构图,
# 而且其外观比只使用 CLASS_DIAGRAMS 时更丰富,默认为 YES。
CLASS_GRAPH = YES
# 如果 HAVE_DOT 标记和这个标记同时设置为 Yes,doxygen 会生成协作图(还有继承图),
# 显示各个类成员(即包含)及其继承层次结构,默认为 YES。
COLLABORATION_GRAPH = YES
GROUP_GRAPHS = YES
UML_LOOK = NO
TEMPLATE_RELATIONS = NO
INCLUDE_GRAPH = YES
INCLUDED_BY_GRAPH = YES
# 在程序文档中允许以图例形式显示函数调用关系,前提是你已经安装了 graphviz 软件包
CALL_GRAPH = YES
# 在程序文档中允许以图例形式显示函数调用关系,前提是你已经安装了 graphviz 软件包
CALLER_GRAPH = YES
GRAPHICAL_HIERARCHY = YES
DIRECTORY_GRAPH = YES
DOT_IMAGE_FORMAT = png
DOT_PATH =
DOTFILE_DIRS =
DOT_GRAPH_MAX_NODES = 50
MAX_DOT_GRAPH_DEPTH = 0
DOT_TRANSPARENT = NO
DOT_MULTI_TARGETS = YES
GENERATE_LEGEND = YES
DOT_CLEANUP = YES
六、程序文档的生成:
程序文档的生成只需将终端的当前目录定位在有 doxygen 配置文件的目录,
然后键入 doxygen 配置文件名 即可!
如果是用 doxygen -s -g 或 doxygen -g 生成的名为 Doxygen 的配置文件,那么可以在终端里
仅键入 doxygen 命令即可生成程序文档。
文章来源:http://blog.sina.com.cn/s/blog_4c451e0e0100gixe.html