Doxygen配置输出HTML文档

简介

  Doxygen是一个文档系统工具，用于从已按照一定规则进行注释的源代码中提取记录信息，生成文档。

信息流图

  请先浏览一下Doxygen的信息流图，对各个工具和信息流之间的关系先有一个大概的了解。

检查编程语言是否被支持

  Doxygen默认支持：C, C++, C#, Objective-C, IDL, Java, VHDL, PHP, Python, Fortran and D。其他语言可以通过预处理器来扩展支持，这里不展开讨论。

设置配置文件

  可以通过命令来生成一个配置文件，然后根据需求修改配置文件。也可以使用 GUI 向导工具 doxywizard 来进行配置。这里选择使用向导工具来进行配置，这可以快速完成配置而保持多数配置为默认值，也可以通过Expert选项卡进一步微调。

Project配置向导

Mode配置向导

Output配置向导

Diagrams配置向导

输出文档

更精细的配置

Project配置

OUTPUT_LANGUAGE 标签

  该标签用于设置生成文档的语言。

JAVADOC_BANNER 标签

  如果使用了/***************（两个以上的星号）开头的注释，默认是不提取该注释的，若希望把它当作/**一样处理，则需要勾选该标签。

JAVADOC_AUTOBRIEF 标签

  勾选该标签后，会自动将注释的第一行（直到第一个英文句号.）解释为简要描述。这不适合中文习惯，因为要使用英文句号.而不能使用中文句号。。不勾选该标签则应该显式使用\brief命令引入简要描述。

TAB_SIZE 标签

  该标签用于设置将代码片中的制表符替换为多少个空格。

Build配置

EXTRACT_ALL 标签

  勾选该标签后，所有文件都会被提取信息然后生成文档。不勾选该标签则只有使用了@file（或\file）命令的文档才会被提取信息然后生成文档。

Input配置

INPUT 标签

  该标签用于设置输入文件的文件路径/目录路径，留空则为当前目录。

INPUT_ENCODING 标签

  该标签用于指明输入文件所使用的字符编码。

FILE_PATTERNS 标签

  该标签用于设置选择哪些类型的文件作为输入。如果留空则默认为以下类型文件：

*.c, *.cc, *.cxx, *.cpp, *.c++, *.java, *.ii, *.ixx, *.ipp, *.i++, *.inl, *.idl, *.ddl, *.odl, *.h, *.hh, *.hxx, *.hpp, *.h++, *.cs, *.d, *.php, *.php4, *.php5, *.phtml, *.inc, *.m, *.markdown, *.md, *.mm, *.dox (to be provided as doxygen C comment), *.py, *.pyw, *.f90, *.f95, *.f03, *.f08, *.f18, *.f, *.for, *.vhd, *.vhdl, *.ucf, *.qsf and *.ice.

  也可以扩展自定义类型文件，这里不展开讨论。

RECURSIVE 标签

  该标签用于设置是否搜索子目录。

EXCLUDE 标签

  该标签用于设置要排除的文件路径/目录路径。

HTML配置

DISABLE_INDEX 标签

  该标签用于打开/关闭每个HTML页面顶部的压缩索引（选项卡）。

GENERATE_TREEVIEW 标签

  该标签用于指定是否生成侧边栏导航页来显示分层信息。

Preprocessor配置

ENABLE_PREPROCESSING 标签

  勾选该标签则doxygen将计算源文件和包含文件中的所有c预处理器指令，但不执行宏展开。

/* 假设有如下文档 */
#define VERSION 200
#define CONST_STRING const char *
#if VERSION >= 200
	static CONST_STRING version = "2.xx";
#else
	static CONST_STRING version = "1.xx";
#endif

/* 勾选ENABLE_PREPROCESSING，经doxygen解析后 */
#define VERSION
#define CONST_STRING
	static CONST_STRING version = "2.xx";	//CONST_STRING不会展开

/* 不勾选ENABLE_PREPROCESSING，经doxygen解析后 */
#define VERSION
#define CONST_STRING
	static CONST_STRING version = "2.xx";
	static CONST_STRING version = "1.xx";

MACRO_EXPANSION 标签

  勾选该标签则doxygen将在源代码中展开所有宏名。

/* 假设有如下文档 */
#define VERSION 200
#define CONST_STRING const char *
#if VERSION >= 200
	static CONST_STRING version = "2.xx";
#else
	static CONST_STRING version = "1.xx";
#endif

/* 勾选MACRO_EXPANSION，经doxygen解析后 */
#define VERSION
#define CONST_STRING
	static const char * version = "2.xx";    //CONST_STRING宏展开

/* 不勾选MACRO_EXPANSION，经doxygen解析后 */
#define VERSION
#define CONST_STRING
	static CONST_STRING version = "2.xx";    //CONST_STRING宏不展开