ASPICE SWE3之——C代码生成软件详细设计1 Doxygen配置

目录

1 前言

2 Doxygen简介

2.1 什么是Doxygen

2.2 安装Doxygen及辅助软件

2.3 Doxygen的配置

1 前言

        前面已经单独一篇文章讲了，若想通过Doxygen工具生成C代码的软件详细设计文档，需要C代码注释的格式，并推荐了注释规范，以满足Doxygen工具识别格式，且符合ASPICE对详细设计的内容要求，且尽可能使注释内容简洁并生成报告好看。

        本文接下来讲，若想通过Doxygen工具生成C代码的软件详细设计文档，需要下载哪些软件，软件包放在资源中需要自取，Doxygen工具该如何配置，若想生成报告成功需要注意什么。

        配置项上参考了一些网上推荐的配置，使用时仍会出现一些的问题，经过不停尝试，最终生成报告成功，遂又总结了一下这些配置。

2 Doxygen简介

2.1 什么是Doxygen

Doxygen 是一个程序的文件产生工具，可将程序中的特定批注转换成为说明文件。可以结合graphviz软件生成函数调用关系图。

2.2 安装Doxygen及辅助软件

1）安装 Doxygen1.9.1

2）安装 graphviz2.38(Windows)

graphviz是一个开源工具包，用于绘制DOT语言脚本描述的图形。Doxygen使用graphviz可自动生成类之间和文件之间的调用关系图。

3）安装 Windows Help Workshop

Doxygen 使用这个工具可以生成CHM格式的文档。

2.3 Doxygen的配置

如果想打开GraphViz的界面，需要进入bin安装目录，找到如下图所示的应用程序，打开运行即可。

所有软件下载安装完成后，打开Doxygen应用程序，位置如下图所示。

1）加载保存好的配置文件Doxygen_demo_config

若加载如上已有配置，仅需再手动配置下面第2、6、9中需要添加路径的步骤。

也可按如下所有步骤进行私人配置后进行保存，方便下次使用。

2)打开Doxygen GUI frontend，按下图所示方法配置

2）指定源码输出模式

3）选择输出文件的格式

4）选择是否使用生成图表的软件包

点击Expert标签（若继续点击next会进入Run）

在选择这个选项之前需要确保先安装了Graphviz工具包。

5）编译的设置

点击Expert标签，进入Build小标签下，按如下图所示方法配置。

EXTRACT_ALL 表示：输出所有的函数，但是private和static函数不属于其管制。

EXTRACT_PRIVATE 表示：输出private函数。

EXTRACT_STATIC 表示：输出static函数。同时还有几个EXTRACT，相应查看文档即可。

HIDE_UNDOC_MEMBERS 表示：那些没有使用doxygen格式描述的文档（函数或类等）就不显示了。当然，如果EXTRACT_ALL被启用，那么这个标志其实是被忽略的。

INTERNAL_DOCS 主要指：是否输出注解中的@internal部分。如果没有被启动，那么注解中所有的@internal部分都将在目标帮助中不可见。

CASE_SENSE_NAMES 表示：是否关注大小写名称，注意，如果开启了，那么所有的名称都将被小写。对于C/C++这种字母相关的语言来说，建议不要开启。

HIDE_SCOPE_NAMES 表示：域隐藏，建议不要开启。

SHOW_INCLUDE_FILES 表示：是否显示包含文件，如果开启，帮助中会专门生成一个页面，里面包含所有包含文件的列表。

INLINE_INFO ：如果开启，那么在帮助文档中，inline函数前面会有一个inline修饰词来标明。

SORT_MEMBER_DOCS ：如果开启，那么在帮助文档列表显示的时候，函数名称会排序，否则按照解释的顺序显示。

GENERATE_TODOLIST ：是否生成TODOLIST页面，如果开启，那么包含在@todo注解中的内容将会单独生成并显示在一个页面中，其他的GENERATE选项同。

SHOW_USED_FILES ：是否在函数或类等的帮助中，最下面显示函数或类的来源文件。

SHOW_FILES ：是否显示文件列表页面，如果开启，那么帮助中会存在一个一个文件列表索引页面。

6）输出的设置

点击Expert标签下的Dot标签后，这里配置我们安装的GraphViz

7）中文版报告设置

若使用英文注释，可不设置该项。

进入Project标签，设置语言为Chinese即可

 

8）Doxygen支持中文注释的方法

以下仅提供方法，若使用英文注释，可不设置该项。

Export->Project-> DOXYFILE_ENCODING GBK/GB2312

Export->Input->INPUT_ENCODING GBK/GB2312

 

9）生成.chm格式的报告

10）开始编译生成html报告

Run标签下，点击 Run Doxygen即可。如下图所示（根据你源代码的大小，等待的时间不同，直到出现finished），最后点击“Show HTML output”可打开HTML格式报告。

11）在报告路径下打开.chm格式的文件

由于HTML格式报告包含太多文件，容易丢失。详设报告使用.chm格式报告，在HTML报告路径下。