參考：http://www.cnblogs.com/zyl910/archive/2013/06/07/objcdoc.html
對于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
一、注釋寫法
提示：這一章主要是參考性内容，比較枯燥。請根據需要來閱讀——
對于想簡單學一下注釋寫法的，讀前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種行尾注釋——
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
源碼下載下傳——
https://files.cnblogs.com/zyl910/objcdoc.zip
感謝此部落客 zyl910 寫的如此多，全文copy還望海涵