使用doxygen

Getting started with Doxygen

可执行文件doxygen是解析源文件并生成文档的主程序.

另外, 也可以使用可执行文件doxywizard, 是用于编辑配置文件, 以及在图形环
境下使用doxygen的图形前端.

• doxygen
  • 读取源文件
  • 读取自定义的, header,footer,image
  • 读取, 生成: tag文件
  • 读取, 生成: layout文件
  • 读取, 生成, 更新: 配置文件, doxyfile <=> doxywizard
  • 生成: XML文件
  • 生成: latex文件+makefile => make ps, make pdf => 生成ps,PDF
  • 生成: man page
  • 生成: refman.rtf => word导入
  • 生成: html页面

step 0: 检查doxygen是否支持你使用的编程语言

xxx

step 1: 创建一个配置文件

Doxygen使用一个配置文件来决定所有的设置. 每个项目都应该有它自己的配置文件. 项目
可以只由一个配置文件构成, 也可以是递归扫描得到的整个源文件树

为了简化配置文件的创建, doxygen可以替你创建一个模板配置文件. 如果需要这样的话,
使用-g选项调用doxygen:

doxygen -g 

其中config-file是配置文件的名称. 如果你省略了文件名, 会创建一个名为Doxyfile的文
件. 如果已经有一个叫做config-file的文件, doxygen会先将其重命名为config-file.bak.
如果你使用-做为文件名, doxygen会试图从标准输入中读取配置文件, 对脚本有用.

配置文件可以

配置文件格式类似makefile. 由一系列的赋值(tags)构成:

TAGNAME = VALUE

or

TAGNAME = VALUE1 VALUE2...

你可以让生成的模板配置的多数配置保留默认值就好.

如果不想要使用文本编辑器编辑配置文件, 你应该看一下doxywizard, 这个是一个可以创
建, 读取, 写入doxygen配置文件的GUI前端, xxx

对于由少数C/C++源文件和头文件构成项目, 可以留空INPUT, doxygen会在当前目录下搜
索源文件.

如果你有一个更大代码树, 应该将INPUTtag设置为根目录(或者多个目录), 并且在
FILE_PATTERNStag中添加一个或者多个文件模式(比如*.c *.h). 只有匹配其中的
pattern的文件会被解析(如果pattern缺省, 会使用doxygen支持的文件类型的典型
pattern). 要递归parsing代码树的话, 你需要设置RECURSIVEtag为YES. 要进一步微调要
解析的文件列表, 可以使用EXCLUDE或者EXCLUDE_PATTERNStag. 比如, 要忽略源代码树
中所有的测试目录, 可以使用:

EXECLUDE_PATTERNS = */test/*

doxygen会根据文件的拓展来决定如何解析一个文件:

• .dox,doc,.c,.h,.txt: C/C++
• .md,.markdown: Markdown
• ..

其他的拓展, 如果没有加入到FILE_PATTERNS并且恰当设置EXTENSION_MAPPING, 不会
parse

如果你开始在一个已有的项目(没有任何doxygen了解的文档)中使用doxygen, 你仍然可以大
致了解结构是怎样的, 文档生成的结果大概是什么. 如果需要这样的话, 必须在配置文件中
设置EXTRACT_ALLtag为YES. 然后, doxygen会认为你的代码中所有的东西都是已经记录了
文档. 要注意, 在EXTRACT_ALL设置为YES的时候, 会warning xxx

要分析软件已有的一部分, 交叉引用源文件中一个(已有记录)实体的定义是很有用的. 如果
你将SOURCE_BROWSERtag设置为YES.

也可以设置INLINE_SOURCES为YES来将源文件直接包含到文档中(比如在code reviews的时
候是很好用的)

step 2: 运行doxygen

要生成文档, 可以使用:

doxygen 

根据你的设置, doxygen会在输出目录中创建html,rtf, latex, xml, man, 以及/或者
docbook目录....

默认的输出目录是调用doxygen的目录. 输出要写入的根目录可以使用OUTPUT_DIRECTORY
改变. 格式特定的目录可以使用 HTML_OUTPUT, RTF_OUTPUT, LATEX_OUTPUT,
XML_OUTPUT,MAN_OUTPUT,以及DOCBOOK_OUTPUTtag来选择. 如果输出目录不存在,
doxygen会试图替你创建它(但是不会试图递归创建整个目录(mkdir -p))

HTML输出

生成的HTML文档可以通过html文件中的index.html文件浏览. 最好是使用支持CSS的浏览器

部分HTML部分特性(比如GENERATE_TREEVIEW或者搜索)要求浏览器支持动态HTML和JavaScript.

LaTeX输出

生成的LaTeX文档必须先由LaTeX编译器编译. 为了简化编译生成的文档的过程, doxygen在
latex目录中写了一个Makefile..

Makefile的内容和target屈居于USE_PDFLATEX的设置, 如果未启用(NO), 那么make会生成
dvi文件. 可以使用xdvi浏览或者转换为PostScript文件(make ps)..

Man page输出

生成的man page可以使用man程序浏览. 你需要确保man目录处于man path(MANPATH环境变量
)中. man page有一些限制..

Step 3: Documenting the sources

尽管源代码的记录是当做第三步给出, 在一个新的项目中, 这当然应该是step 1. 这里我认
为你已经有一些代码, 并且想要doxygen来生成一个描述API的良好文档, 以及, 可能的内部
细节和一些相关设计文档.

如果配置文件中的EXTRACT_ALL设置为NO(默认的), 则doxygen只会为有记录的实体生成文
档. 所以, 你如果记录呢? 对于成员, 类, 以及名称空间, 有两个基本选项:

1. 在member, class, namespace的声明之前添加一个special文档块. 对于file, class,
   以及namespace成员, 也可以将文档直接置于member之后.
2. 在别的地方(另一个文件或者另一个位置)置special文档块并且在文档块中加一个
   structural command. 结构化命令将一个文档块链接至一个可以被记录的实体(member,
   class,namespace或者文件)

第一个选项的有点是, 你不需要重复实体的名称.

文件只能使用第二个选项记录, 因为没有法子在文件之前加文档块. 当然, 文件成员(函数,
变量, typedef, defines)必须要明确的结构化命令: 在其之前或者之后添加一个特殊文档
块就可以了

特殊文档块中的文本在写入HTML或者LaTeX输出文件之前会被解析:

在解析的过程中, 会进行如下步骤:

• markdown格式话或替换为对应的HTML或者特殊命令
• 文档中的特殊命令会执行
• 如果一行由一些空格加上一个或者多个*起始, 所有的空格或者*都会被移除(C注习惯
  )
• 所有生成的空白行都当做是段落分隔符. 你就没得必要在自己使用new-paragraph命令
  来增加可读性了.
• 对于关联了有记录的类的word(除非word前缀了%, 这个情况下不会链接, 并且%会移除)
• 当在文本中碰到了特定的pattern的时候会创建到member的链接
• 文档中的HTML tags会解释, 并且在LaTeX输出中会转换为LaTeX等价的形式.