作者：zyl910
手工寫文檔是一件苦差事，幸好現在有從源碼中抽取註釋生成文檔的專用工具。對於Objective-C來說，目前最好用的工具是appledoc和doxygen。可是這兩種工具對於註釋的要求略有區別。於是我經過一番摸索，找到了一套能同時兼容這兩種工具的註釋寫法。
工具簡介——
appledoc：簡單方便，適於生成apple風格的html文檔，及直接集成到xcode幫助（docset）。官網 http://gentlebytes.com/appledoc/ 。
doxygen：功能強大，適於生成html文檔與pdf文檔。官網 http://www.stack.nl/~dimitri/doxygen/index.html 。
系統環境——
Mac OS X Lion 10.7.5
Xcode 4.6.2
appledoc 2.1
doxygen 1.8.4
MacTeX-2012
一、註釋寫法
提示：這一章主要是參考性內容，比較枯燥。請根據需要來閱讀——
對於想簡單學一下注釋寫法的，讀前4節就行了；
對於想全面學習appledoc與doxygen均兼容的註釋寫法的，讀前6節就行了；
對於既想使用appledoc，又想使用doxygen增強效果的，請閱讀所有的節。
1.1 註釋形式
標準C/C++的註釋形式有“//”形式的單行註釋 與“/* */”形式的多行註釋這兩種。
而appledoc與doxygen的文檔化註釋是它們的變種，有多種形式。例如appledoc與doxygen均兼容的註釋形式有以下7種——
/// Single line comment. /// Single line comment spreading /// over multiple lines. /** Single line comment. */ /** Single line comment spreading * over multiple lines. */ /** Single line comment spreading over multiple lines. No star. */ /*! Single line comment. */ /*! Single line comment spreading over multiple lines. */
雖然appledoc與doxygen都支持。但在平時編寫代碼時，爲了避免風格雜亂的視覺污染，應該固定使用註釋形式。
1.1.1 單行註釋
在很多時候只需寫一個簡要描述就夠了，這時最好使用單行註釋。推薦格式爲——
///
簡要描述. |
appledoc與doxygen均會將單行的“///”註釋識別爲簡要描述。兼容性非常高。
備註——
1) 文本最好統一以英文句號（.）結尾。這樣做有助於代碼閱讀，明確地得知該段文本已經結束，而且有助於避免亂碼時的換行符丟失問題。
2) 不要連續多行使用“///”。doxygen在默認情況下，會將多行的“///”當作詳細描述，而沒有簡要註釋. 雖然可以修改doxygen的配置以解決上述問題，但多行“///”本身是違背“簡要描述”這個初衷的.
1.1.2 多行註釋
當需要寫詳細描述時，這時就需要使用多行註釋了。推薦格式爲——
/** 簡要描述. * * 詳細描述或其他. */
對於appledoc與使用了JAVADOC_AUTOBRIEF參數的doxygen來說，它們均會將註釋中的第一段識別爲簡要描述，然後將後面的段識別爲詳細描述.
其實doxygen的標準多行註釋爲——
/** * @brief 簡要描述. * * 詳細描述或其他. */
可惜appledoc對@brief指令的支持存在缺陷——@brief不能出現類、協議的註釋中，會導致後續內容丟失。 @brief多行註釋僅能安全的用在屬性、方法的註釋中。
備註——
1) 多行註釋存在“段”的概念，以內容爲空的行作爲分段依據。如果沒有空行隔開的話，會將連續有內容的行連接起來組成一段.
2) 如果省略中間各行行首的星號（*），appledoc與doxygen也能識別。當考慮到註釋縮進、美觀性、兼容性，還是建議不要省略行首星號。
1.1.3 行尾註釋（僅doxygen）
在對枚舉、結構體等類型的成員進行註釋時，爲了使內容更加緊湊，我們一般喜歡在行尾寫註釋。
可惜目前僅有doxygen支持行尾註釋，而appledoc不支持。
doxygen支持以下4種行尾註釋——
/**< 行尾註釋1. appledoc不支持會變爲下一項的註釋, doxygen 支持, 根據英文句號自動切分簡要描述與詳細描述. */ /*!< 行尾註釋2. appledoc不支持會變爲下一項的註釋, doxygen 支持, 會全部當作詳細描述, 而缺少簡要描述. */ ///< 行尾註釋3. appledoc不支持會變爲下一項的註釋, doxygen 支持. //!< 行尾註釋4. appledoc不支持會會忽略, doxygen 支持.
爲了避免appledoc誤將行尾註釋當作下一項的註釋，故推薦第4種註釋——既以“//!<”開頭的註釋。
1.2 類（協議、分類）的註釋
對於類（協議、分類）來說，一般只需要寫簡要描述就行了，這時可以使用單行註釋——
/// 文檔A. @interface DocA : NSObject
當需要留下詳細描述時，可換成多行註釋——
/** 文檔B. * * 文檔B的詳細描述. */ @interface DocB : NSObject
1.3 屬性的註釋
對於屬性來說，本來使用行尾註釋是最好的，能使內容更加緊湊。可惜目前appledoc不支持行尾註釋。只好退而求其次，選擇單行註釋了——
/// 數值屬性. @property (nonatomic,assign) NSInteger num;
當需要留下詳細描述時，可換成多行註釋——
/** * @brief 字符串屬性. * * 屬性的詳細描述. */ @property (nonatomic,strong) NSString* str;
1.4 方法的註釋
對於沒有參數、返回值的簡單方法，可以使用單行註釋——
/// 簡單方法. - (void)someMethod;
若方法具有參數或返回值，這時就得使用多行註釋了——
/** * @brief 帶整數參數的方法. * * @param value 值. * * @return 返回value. */ - (int)someMethodByInt:(int)value;
指令說明——
@param <name> <description>: 參數描述.
@return <description>: 返回值描述.
由於方法註釋需要填寫的內容較多（參數列表與返回值等），所以現在有很多插件可以幫忙生成方法的註釋，而這些插件一般是使用@brief多行註釋的。例如參考文獻中的《Xcode4快速Doxygen文檔註釋 — 簡明圖文教程（3分鐘後爽歪歪）》.
在某些時候，我們還需要在方法註釋種填寫異常、參見、警告 等信息——
/** * @brief 帶字符串參數的方法. * * @param value 值. * * @return 返回value. * * @exception NSException 可能拋出的異常. * * @see someMethod * @see someMethodByInt: * @warning 警告: appledoc中顯示爲藍色背景, Doxygen中顯示爲紅色豎條. * @bug 缺陷: appledoc中顯示爲黃色背景, Doxygen中顯示爲綠色豎條. */ - (NSString*)someMethodByStr:(NSString*)value;
指令說明——
@exception <name> <description>: 異常描述.
@see <name>: 參見. 具體用法詳見 1.5.2 @see、@sa（參見） .
@warning <text>: 警告.
@bug <text>: 警告.
1.5 appledoc、doxygen均支持的指令
指令一般以“@”開頭，也可以使用“\”等符號開頭。 若想在文本中使用“@”、“\”等符號，可使用“\”轉義符，例如“\@”、“\\”等。
1.5.1 指令列表
指令在appledoc中被稱作“Directive”，而在doxygen中被稱作“Command”。
appledoc沒有專門指令參考文檔，僅在《Comments formatting style》中給了幾個簡單示例。
而doxygen有詳細的指令參考文檔，詳見《Special Commands》。
經過測試，我發現下列指令在appledoc與doxygen中均是有效的——
@brief <title>: 簡要註釋. appledoc中僅對屬性、方法有效，對類、協議 無效，會造成後續內容解析失敗.
@param <name> <description>: 參數描述.
@return <description>: 返回值描述.
@exception <name> <description>: 異常描述.
@see <name>: 參見.
@sa <name>: 參見. 同@see.
@warning <text>: 警告.
@bug <text>: 警告.
@name <title>: 組名. 用於給成員們分組, 既文檔中Tasks區的子類別.
1.5.2 @see、@sa（參見）
參見指令的格式爲——
@see <name>
@sa <name>
在保證appledoc與doxygen均兼容的情況下，<name>可爲——
1) 當前類（或協議）中的屬性或方法。（注意Objective-C方法簽名的寫法，一般爲“方法名:參數1:參數2:⋯⋯”的格式）
2) 類（或協議）名。（注意appledoc不支持當前類）
雖然appledoc與doxygen都支持參見“其他類或協議中的成員”，可惜它們的寫法不同，而且相互不兼容——
appledoc：使用Objective-C消息語法，既“[類 成員]”格式。
doxygen：使用傳統的對象成員訪問語法，既“類.成員”格式。
注意本指令與@brief指令存在同樣的問題——appledoc中僅對屬性、方法有效，對類、協議 無效，會造成後續內容解析失敗。 這時有兩種處理策略——
1) 將參見指令放在註釋的最後面，避免內容丟失，且能保證在doxygen中的效果.
2) 使用鏈接來代替參見。詳見 1.6.4 鏈接。
1.6 appledoc、doxygen均支持的排版格式
無格式的純文本看起來比較費勁，得進行格式排版，以提高文檔的組織性與表現力。appledoc與doxygen均有自己的一套約定——
appledoc可參考《Comments formatting style》。
doxygen可參考《Markdown support》。
本節將會介紹appledoc與doxygen均支持的排版格式。
1.6.1 代碼文本
有時需要在一段話中引入一小段代碼，這時可以用重音符（`）將那一段代碼給包起來。例如——
/** * 引用短代碼, 如 `someMethodByStr:` . */
1.6.2 代碼塊
代碼塊適用於需要在註釋中放置多行代碼的情況。具體辦法是在每行內容的前面加一個tab字符，例如——
/** * 示例代碼: * * int sum=0; * for(int i=1; i<=10; ++i) { * sum += i; * } */
因爲空格與Tab字符均顯示爲空白，不易區分。於是用<space>、<tab>表達空格與tab字符，上述註釋實際爲——
/** <space>*<space>示例代碼: <space>* <space>*<space><tab>int sum=0; <space>*<space><tab>for(int i=1; i<=10; ++i) { <space>*<space><tab><tab>sum += i; <space>*<space><tab>} <space>*/
因每行註釋開始的星號（*）與內容之間必須用空白型字符隔開，所以平時用空格或tab字符都行。但在使用代碼塊時，爲了避免對Tab字符的誤判，內容最好嚴格以“<space><tab>”開頭（既每行以“<space>*<space><tab>”開頭）。
備註——
1) 注意段的概念，代碼塊與前後文本之間應該空開一行。
2) appledoc與doxygen還支持將4個空格當作一個tab字符。但4個字符的錄入、維護起來會更費力一些，不推薦使用。
1.6.2.1 xcode中輸入代碼塊
在xcode中，按下Tab鍵時，會自動整合前面的空格字符，導致代碼塊排版失效。所以建議先在多行註釋中粘貼代碼，然後在行前輸入“*<space><tab>”。範例如下——
首先，最初的註釋是這樣的——
/** * @brief 簡要描述. * * 詳細描述或其他. */
第一步，在多行註釋中粘貼代碼，注意xcode會自動對新粘貼內容進行排版，在每一行的前面加一個空格——
/** * @brief 簡要描述. * * 詳細描述或其他. int sum=0; for(int i=1; i<=10; ++i) { sum += i; } */
第二步，補齊行首。複製“*<space><tab>”，對於先前所粘貼的那段代碼，在每一行的第二個字符處粘貼，以形成“<space>*<space><tab>”開頭的代碼塊格式——
/** * @brief 簡要描述. * * 詳細描述或其他. * int sum=0; * for(int i=1; i<=10; ++i) { * sum += i; * } */
第三步，修尾。增加空行，增加“代碼:”行，提示下面是代碼——
/** * @brief 簡要描述. * * 詳細描述或其他. * * 代碼: * * int sum=0; * for(int i=1; i<=10; ++i) { * sum += i; * } */
1.6.3 列表
1.6.3.1 無序列表
在內容的每一行開頭使用“-”、“+”或“*”字符，可創建無序列表。例如——
/** * 無序列表: * * - abc * - xyz * - rgb */
1.6.3.2 有序列表
使用數字與小數點，可創建有序列表。例如——
/** * 有序列表: * * 1. first. * 2. second. * 3. third. */
1.6.3.3 多級列表
使用tab字符配合使用無序列表或多級列表，可創建多級列表。例如——
/** * 多級列表: * * - xyz * - x * - y * - z * - rgb * - red * 1. first. * 1. alpha. * 2. beta. * 2. second. * 3. third. * - green * - blue */
1.6.4 鏈接
鏈接有三種形式——
1) 直接鏈接。格式爲 <link>。會將鏈接地址直接作爲文本來顯示。
2) 文本鏈接。格式爲 [text](<link>)。使用自定義的文本作爲鏈接名。
3) 交叉引用鏈接。比較複雜，且難以兼容appledoc與doxygen，故本文不討論。
1.6.4.1 Url
在註釋中直接寫上url便會自動創建鏈接，例如——
/** * http://appledoc.gentlebytes.com/ : 直接寫url鏈接. */
還可以使用文本鏈接形式——
/** * [Doxygen](http://www.stack.nl/~dimitri/doxygen/) : 爲鏈接提供文本 . */
1.6.4.2 類與協議
在註釋中直接寫上類（或協議）名，並注意左右兩側留空格，appledoc與doxygen便會自動生成指向該類（或協議）的鏈接。例如——
/** * DocA : 類. */
但對於文本鏈接來說，appledoc與doxygen的寫法不同——
/** * - [文檔B](DocB) : 類的鏈接文本.（僅appledoc） * - [文檔B](@ref DocB) : 爲\@ref鏈接提供文本 （僅doxygen. appledoc會把\@ref當作文本而生成錯誤的鏈接）. */
建議還是使用直接鏈接吧。
1.6.4.3 屬性與方法（僅appledoc）
如果註釋中出現了 [類 成員]，appledoc會自動的爲其創建鏈接，但doxygen不支持此功能。
如果註釋中出現當前類的屬性或方法名，appledoc會自動的爲其創建鏈接，但doxygen不支持此功能。而且appledoc還存在Bug——如果在同一片註釋中出現了[類 成員]，那麼當前類的的屬性或方法的鏈接會失效。
這麼不穩定的功能還是暫時別用吧。
1.7 常用的doxygen註釋示例
doxygen的註釋功能多的令人眼花繚亂，這裏還是介紹幾種常用寫法吧。
1.7.1 文件頭
一般格式爲——
/** * @file MyDocViewController.h * @brief 主頁面. * @author [zyl910](http://www.cnblogs.com/zyl910/) * @version 1.0 * @date 2013-06-07 * * # update （更新日誌） * * [2013-06-07] <zyl910> v1.0 * * + v1.0版發佈. * */
指令說明——
@file [<name>]：文件名.
@author <list of authors>：作者. 這裏我使用了鏈接，詳見 1.6.4 鏈接 .
@version <version number>：版本號.
@date <date description>：日期.
以井號（#）開頭的行表示是標題。如果有1個井號（#），表示是一級標題。如果有2個井號（##），表示是二級標題，以此類推。
1.7.2 枚舉、結構體、聯合體與typedef
對於枚舉、結構體、聯合體等類型，一般可選用單行註釋或多行註釋。對於其中的成員，推薦使用行尾註釋。例如——
/// Objective-C 文檔工具枚舉 （枚舉, 僅Doxygen）. typedef enum _ObjCDocToolEnum{ ObjCDocToolEnumAppleDoc = 1, //!< AppleDoc. http://appledoc.gentlebytes.com/ . ObjCDocToolEnumDoxygen, //!< Doxygen. http://www.stack.nl/~dimitri/doxygen/ . }ObjCDocToolEnum; /** 整數矩形 （結構體, 僅Doxygen）. * * 結構體的詳細描述. */ typedef struct _RectInt { int x; //!< 橫座標. int y; //!< 縱座標. int width; //!< 寬度. int height; //!< 高度. }RectInt, *PRectInt; //!< 整數矩形的指針. typedef const RectInt* PCRectInt; //!< 整數矩形的常量指針. /// 浮點數的字節（聯合體, 僅Doxygen）. typedef union _FloatByte { float f; //!< 單精度浮點數. unsigned char bytes[4]; //!< 4個字節. } FloatByte;
注意行尾註釋是對前一項的註釋，所以一定要使用分號（;）或逗號（,）標明本項成員定義好後，再寫行尾註釋。包括最後一個成員。
在定義結構體時，一般還需要定義其相關的指針類型與常量指針類型——
定義指針類型時，可以跟結構體的定義寫在一起，利用行尾註釋的特點來註釋。
定義常量指針類型時，需要單獨寫一行typedef，並使用行尾註釋。
1.7.3 宏
對於常量形式的簡單宏，推薦使用行尾註釋。例如——
#define BUFSIZE 100 //!< 緩衝區大小 （簡單宏, 僅Doxygen）.
對於帶參數的宏，可參考“方法的註釋”寫多行註釋。例如——
/** * @brief 最小值 （參數宏, 僅Doxygen）. * * @param a 值a. * @param b 值b. * * @return 返回兩者中的最小值. */ #define min(a,b) ( ((a)<(b)) ? (a) : (b) )
1.7.4 函數指針與塊函數（Block Objects）
對於函數指針與塊函數，也可參考“方法的註釋”寫多行註釋。例如——
/** * @brief 動作回調函數. * * @param sender 發送者. * @param userdata 自定義數據. */ typedef void (*ActionCallback)(void* sender, void* userdata); /** * @brief 動作塊函數. * * @param sender 發送者. * @param userdata 自定義數據. */ typedef void (^ActionHandler)(id sender, id userdata);
1.7.5 成員變量
對於成員變量，推薦使用行尾註釋。例如——
@interface MyDocViewController : UIViewController { @private int _privateInt; //!< 私有成員變量 (僅Doxygen具有EXTRACT_PRIVATE標識時, 會被歸類爲“Private 屬性”). @protected int _protectedInt; //!< protected成員變量 (僅Doxygen, 會被歸類爲“Protected 屬性”). id<MyDocDelegate> _delegate; //!< 委託變量. @package int _packageInt; //!< 包內成員變量 (僅Doxygen, 會被歸類爲“Protected 屬性”). @public int _publicInt; //!< 公開成員變量 (僅Doxygen, 會被歸類爲“Public 屬性”). }
二、編碼演練
前面說了很多理論知識，現在創建一個項目來演練一下吧。
打開Xcode，新建一個名爲“MyDoc”的“Single View Application”的iOS項目。
然後打開MyDocViewController.h，在裏面練習註釋。
全部代碼——
MyDocViewController.h
代碼寫好後，便可以使用appledoc或doxygen生成文檔了，詳見下面兩章。
三、使用appledoc生成文檔（docset、html）
3.1 安裝appledoc
安裝appledoc十分簡單。打開終端，輸入以下命令——
git clone git://github.com/tomaz/appledoc.git cd appledoc sudo sh install-appledoc.sh
3.2 生成docset
對於最新版本的appledoc來說，它默認時是生成docset文檔並集成到xcode。
在終端中使用cd命令進入項目的文件夾，然後執行下列命令——
appledoc --output ./doc --project-name objcdoc --project-company "zyl910" --company-id "cn.com.zyl910" .
注——
--output ./doc：設置輸出目錄爲“./doc”。
--project-name objcdoc：設置項目名爲“objcdoc”。
--project-company "zyl910"：設置公司名爲“zyl910”。
--company-id "cn.com.zyl910"：設置公司id爲“cn.com.zyl910”。
.：當前目錄。
當該命令完成後，打開xcode中的Organizer - Documentation，會發現其中新增了幫助文檔——
3.3 生成html
當需要html文檔時，可以加上“--no-create-docset”——
appledoc --no-create-docset --output ./doc --project-name objcdoc --project-company "zyl910" --company-id "cn.com.zyl910" .
當該命令完成後，使用瀏覽器打開doc/html/index.html——
四、使用doxygen生成文檔（html、pdf）
4.1 安裝doxygen
doxygen支持源碼編譯安裝與dmg安裝。想省事的話，可以選擇dmg安裝。去doxygen官網（http://www.stack.nl/~dimitri/doxygen/download.html）下載最新的dmg。
dmg下載下來後，雙擊加載dmg，然後把.app文件拖入應用程序文件夾，便完成了安裝。
4.2 生成html
doxygen有圖形界面，可通過Launchpad打開。
在step 1中選擇好項目的路徑。
step 2默認是Wizard->Project頁面，在其中——
1) 在“Project name”中填寫項目名。
2) 勾選“Sacn recursively”，掃描所有的子文件夾。
3) 在“Destination directory”中填寫好文檔的輸出目錄。這裏我填的是“docs”。
點擊中間的“Expert”切換Expert->Project頁面，在其中——
1) 將“OUTPUT_LANGUAGE”設爲“Chinese”，使用簡體中文。
2) 勾選“JAVADOC_AUTOBRIEF”，自動將註釋的第1段識別爲簡要描述。
點擊中間的“Run”切換Run頁面，然後點擊“Run doxygen”按鈕生成文檔。
當文檔生成完畢後，使用瀏覽器打開docs/html/index.html——
4.3 生成pdf
doxygen默認會爲生成pdf做好準備。切換到Wizard->Project，會發現它自動勾選了“LaTex”與“as intermediate format for hyperlinked PDF”。
doxygen本身並不能直接輸出pdf文件，而是生成了latex目錄，其中有一個 makefile 文件。若系統中裝好了pdflatex，可在latex目錄中運行“make”命令來生成pdf文件。
怎樣才能裝好pdflatex呢？mac平臺可安裝MacTeX。打開 http://www.tug.org/mactex/ ，下載 MacTeX.pkg (約2.1GB)。MacTeX.pkg下載好後，可雙擊運行，根據嚮導來安裝。
環境裝好之後，當在latex目錄中運行“make”命令來生成pdf文件時，你會發現——純英文文檔能順利生成pdf；而含有中文時，不能順利生成pdf文件。
對於latex排版，doxygen其實已經做了很多準備，比如——源文件是UTF-8編碼，並默認使用了utf8 package。理論上是支持多國語言的。
可對於中文來說，還需要加載 CJKutf8 package，並配置好CJK環境。這才能順利的使用中文。
用文本編輯器打開docxygen生成的latex目錄中的refman.tex。找到“\begin{document}”這一行，將其修改爲——
\usepackage{CJKutf8}
\begin{document}
\begin{CJK}{UTF8}{gbsn}
然後再找到“\end{document}”這一行，將其修改爲——
\end{CJK}
\end{document}
保存並關閉refman.tex。
然後打開終端，使用cd命令進入latex目錄，然後執行“make”命令。
執行完畢後後，該目錄中會出現“refman.pdf”——
參考文獻——
[appledoc]《Comments formatting style》. Gentle Bytes. http://gentlebytes.com/appledoc-docs-comments/
[doxygen]《Markdown support》. doxygen. http://www.stack.nl/~dimitri/doxygen/manual/markdown.html
[doxygen]《Special Commands》. doxygen. http://www.stack.nl/~dimitri/doxygen/manual/commands.html
《Amazing Apple-like Documentation》. 2011-11-29. http://www.cocoanetics.com/2011/11/amazing-apple-like-documentation/
《使用Objective-C的文檔生成工具:appledoc》. 唐巧, 2012-02-01. http://blog.devtang.com/blog/2012/02/01/use-appledoc-to-generate-xcode-doc/
《關於查看自已寫的方法的“描述”(AppleDoc)》. Rainbird, 2012-11-25.http://blog.cnrainbird.com/index.php/2012/11/25/guan_yu_cha_kan_zi_yi_xie_de_fang_fa_de_miao_shu_appledoc/
《用Doxygen爲Objective-C代碼生成文檔》. Seven's, 2011-11-20. http://www.dreamingwish.com/dream-2011/use-doxygen-to-generate-documentation-Objective-C-code.html
《Xcode4快速Doxygen文檔註釋 — 簡明圖文教程（3分鐘後爽歪歪）》. chukong-inc, 2012-05-16. http://blog.chukong-inc.com/index.php/2012/05/16/xcode4_fast_doxygen/
《使用doxygen生成中文pdf文檔》. zyl910, 2013-06-02. http://www.cnblogs.com/zyl910/archive/2013/06/02/doxygen_pdf_chinese.html
源碼下載——
http://files.cnblogs.com/zyl910/objcdoc.zip