0
回答
使用GTK-DOC自动生成API文档
终于搞明白,存储TCO原来是这样算的>>>   

之前很少做从零开始做上层应用和中间层的开发,所以从来没有接触过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过程中被自动覆盖。

文章出处:http://blog.csdn.net/colorant/article/details/4028718

举报
鉴客
发帖于6年前 0回/650阅
顶部