之前很少做从零开始做上层应用和中间层的开发，所以从来没有接触过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 ...
 */

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过程中被自动覆盖。

来源：
作者：彩色蚂蚁
链接：https://blog.csdn.net/colorant/article/details/4028718