作者：劉旭暉 Raymond轉載請註明出處

之前很少做從零開始做上層應用和中間層的開發，所以從來沒有接觸過API文件的自動生成這個話題，一直以為這是個很複雜的工作，最近做一個簡單的專案，有需求自己從頭完整的建立整個專案的框架，所以正好用gtk-doc-tools實踐一把文件的自動生成工作，發現其實還是很簡單易用的，記錄一下一些要點如下。

1相關參考資料

如果你仔細的看過這份手冊，再在實際實踐中處理過一些可能遇到的問題，基本上就不用看我的這篇文件了 ;-)

2工作機制

GTK-Doc是一個用來從C程式碼的註釋中生成API文件的工具，尤其適用於使用gobject物件機制程式設計的專案，並不侷限於

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過程中被自動覆蓋。