使用GTK-DOC自动生成API文档

作者：刘旭晖 Raymond转载请注明出处

Email：[e-mail]

BLOG：http://blog.csdn.net/colorant/

主页：http://sites.google.com/site/rgbbones/

      

之前很少做从零开始做上层应用和中间层的开发，所以从来没有接触过API文档的自动生成这个话题，一直以为这是个很复杂的工作，最近做一个简单的项目，有需求自己从头完整的创建整个项目的框架，所以正好用gtk-doc-tools实践一把文档的自动生成工作，发现其实还是很简单易用的，记录一下一些要点如下。

 

1         相关参考资料

http://library.gnome.org/devel/gtk-doc-manual/stable/ GTK-DOC的官方使用手册

如果你仔细的看过这份手册，再在实际实践中处理过一些可能遇到的问题，基本上就不用看我的这篇文档了 ;-)

 

2         工作机制

GTK-Doc是一个用来从C代码的注释中生成API文档的工具，尤其适用于使用gobject对象机制编程的项目，并不局限于GTK+或GNOME相关library和程序的文档生成。

2.1        主要工作流程

基本上，使用GTK-Doc生成API文档，包括几个步骤：

Ø       在项目相关目录和Build相关文件中添加 GTK-Doc所需参数和相关配置文件。

Ø       在代码中按照一定的格式规范添加注释（于普通的注释相比，只需要添加非常少的额外信息）

Ø       使用标准的Build流程（autogen，configure，make等）编译并生成文档

Ø       修改部分GTK-Doc生成的模板和配置文件，进行一些定制工作，如排除某些函数，定制布局，添加而外的help文档等（这部分工作并不需要每次都做，这些模板和配置文件只在第一次build的时候生成，以后不会自动覆盖）

3         步骤

3.1        添加Build所需内容

Ø       添加目录结构：通常会将API文档创建在docs/reference目录中。根据需求可以创建多个子目录用于不同的模块。另外，在各层目录结构中，添加标准的Makefile.am文件用来包含子目录就不用多说了吧。

Ø       Autogen.sh: 在automake、autoconf等操作之前，添加gtkdocize || exit 1，如果你没有创建autogen.sh，那么你就需要在build之前手工执行gtkdocize命令。 可以使用 gtkdocize –flavour no-tmpl 来限制不生成tmpl模板目录（即不使用中间模板，文档全部内容直接从source code获得）

Ø       Configure.ac: 添加gtk-doc检测的相关宏，如：GTK_DOC_CHECK(1.9) 除了检查GTK-Doc的版本，这个宏还将在configure脚本中添加 –enable-gtk-doc选项，需要注意的是，这个选项默认是disable的

Ø       Makefile.am: 在docs/reference或你创建的其它文档子目录下，拷贝gtk-doc-tools的example Makefile.am（ubuntu中安装在/usr/share/doc/gtk-doc-tools/examples/Makefile.am）并根据实际情况修改里面的内容（每个选项都有具体的解释）。通常你所需要修改的大概会有：

 

模块的名字：DOC_MODULE=

代码的相对路径：DOC_SOURCE_DIR=

文档在哪些文件被修改时需要被重新build，即依赖关系：HFILE_GLOB= , CFILE_GLOB=

需要忽略的文件：IGNORE_HFILES=

3.2        在代码中添加注释

GTK-Doc所识别的注释都是以 “/**” 开头，每行一个 “*”，以”*/” 结尾，中间包含一些特定的关键字或符号用于标明注释的内容和类型，以区别于普通文本。

3.2.1          文件头的格式

首先当然是要给文件添加文件级的注释，格式如下

/**

 * SECTION:meepapp

 * @short_description: the application class

 * @see_also: #MeepSettings

 * @stability: Stable

 * @include: meep/app.h

 *

 * The application class handles ...

 */

 

Ø       SECTION: 文件名

Ø       @short_description: 该文件内容的简单描述

Ø       @see_also: 与该文档相关的内容，符号等

Ø       @stability: 版本稳定性信息

Ø       @include: 使用该文件中的函数，所需要包含的头文件，注意不用写<…>或”…”

3.2.2          函数的注释格式

函数的注释格式大体如下：

/**

 * function_name:

 * @par1:  description of parameter 1

 * @par2:  description of parameter 2

 *

 * The function description goes here.

 *

 * Returns: an integer.

*

* Since: Version

 */

 

Ø       类似@par1: 这样以”@”开头的符号标识了你需要注释的函数参数。

Ø       Returns: 函数的返回信息

Ø       Since: 从哪个版本引入的函数

 

3.2.3          其它

需要注意的一点是，上面这些关键字多数都是可选的，即使不写任何注释，GTK-Doc也会将函数，结构，属性，信号等信息自动的添加到API文档中，只是没有额外的说明信息。另外，static和inline的函数不会被添加到文档中。

结构，属性，信号等注释的格式这里就不多说了，简单的就看看别人的代码怎么写的，要想了解得详细些，就参考gtk-doc的官方手册吧。

3.3        定制最终输出结果

最终的文档会由一个主文件将各个Section的页面链接在一起，这个主文件的SGML/XML模板文件（MODULE-docs.sgml）在第一次build的时候生成，在以后的build中不会被覆盖（即使使用make distclean也不会被删除）。你可以修改这个主文件模板，将输出的section组织在不同的chapter中，或着添加额外的内容等等。

同样，你还可以修改MODULE-sections.txt文件，定制各个Section页面的布局和内容。这个文件同样不会在build过程中被自动覆盖。