iOS文檔註釋

Eclipse和IntelliJ IDEA系的IDE都有自動生成文檔註釋的功能，Xcode雖然安裝了VVDocument，可是仍然感受註釋的功能不是很完善，因而今天整理了一下書寫文檔註釋的一些用法。
首先要說的就是文檔註釋提取的工具：主要是介紹HeaderDoc和appleDoc
1.咱們日常長按option鍵同時鼠標點擊，彈出的文檔就是Xcode會自動使用HeaderDoc生成的。如圖：

2.appleDoc只爲Objective-C服務，能夠在文檔書寫完成以後使用appledoc生成docSet，能生成和Apple一個風格的文檔，以下所示：

而後要說的就是一些編寫文檔註釋的規範了：(注意本文值討論文檔註釋，僅僅做爲解釋說明的註釋不會涉及)

單行註釋

共有如下幾種：
行前註釋：(功能較多，可用做對屬性、方法、類的聲明，一般用做對屬性的聲明)

///

行後註釋：(通常對屬性、成員變量的聲明等)

/**< 
/*!<
///< 
//!<

使用的方法以下：

/// 姓名
@property (nonatomic, copy) NSString *name;

@property (nonatomic, copy) NSString *phone; /**< 電話 */
@property (nonatomic, copy) NSString *address; /*!< 住址 */
@property (nonatomic, assign) float height; ///< 身高
@property (nonatomic, assign) NSUInteger age; //!< 年齡

多行註釋

經常使用如下幾種：(常常用在類聲明和方法聲明以前)

/// line1
/// line2

/**
 * line1
 * line2
 */

/*! line1
 *  line2
 */

示例以下：

/*!
 * Comment
 */
@interface Comment : NSObject

/**
 *  an exmaple
 *
 *  @param obj input parameter
 */
- (void)commonMethod:(id)obj;

/// exmaple 2
/// @param obj input parameter
- (void)commonMethod2:(id)obj;

@end

註釋Tag

在寫方法的文檔註釋的時候多用一些參數說明, 這時候會用到@param標籤，除此以外還有其餘標籤

下面是在全部的方法聲明前使用的標籤：

標籤	Example	含義
@param	@param myValue The value to process.	對方法的參數描述
@result	@result Returns 1 on success, 0 on failure.	對返回值的描述
@return	@result Returns 1 on success, 0 on failure.	和@result.相同
@templatefield	@templatefield base_type The base type to store in the linked list.	Each of the function’s template fields (C++).
@throws	@throws bananas	對拋出異常的描述
@var	@var myVar Description goes here	對局部變量或方法的描述

還有一些能夠在類型定義，方法聲明和頭文件中均可以使用的tag

標籤	Example	含義
@abstract	@abstract write the track to disk	簡短描述，不要超過1行
@apiuid	@apiuid //my_ref/doc/magic	重寫與這個註釋綁定的 API UID (apple_ref)，也就是重寫這個註釋的惟一標識， 使用不當會帶來標識衝突等問題
@attribute @attributelist @attributeblock	@attribute My Attribute Name Value goes here.	添加一個自定義的不必定符合規則的tag
@availability	@availability 10.3 and later	適用版本描述
@brief	@brief write the track to disk	簡短描述
@discussion	@discussion This is what this function does. @some_other_tag	詳細描述
@indexgroup	@indexgroup Name of Group	提供放在發佈頁面的組織信息，若是沒有使用這個tag，會使用來自內部的class或者頭文件的組織信息
@internal	@internal	標記爲內部文檔，若是生成文檔時在命令行設置了 --document-internal，這個文檔纔會被生成
@link	@link //apple_ref/c/func/function_name link text goes here @/link 或者 @link function_name link text goes here @/link 或者 @link function_name @/link	插入一個API ref所在的連接
@namespace	@namespace BSD Kernel	對所處的命名空間的說明
@see	@see apple_ref Title for link	參數與@link相同 若是API reference已經在see或seealso中出現這個tag會被忽略
@seealso	@seealso apple_ref Title for link	參數與@link相同 若是API reference已經在see或seealso中出現這個tag會被忽略
@textblock	@textblock My text goes here @/textblock	@textblock和@/textblock之間出現的tag全都是文檔內容
@updated	@updated 2003-03-14	上次更新的時間

另外有一些關於整個文件的一些文檔註釋tag：

標籤	Example	含義
@author	@author Anon E. Mouse	做者
@charset	@charset utf-8	生成HTML文件使用的編碼，同@encoding
@compilerflag	@compilerflag -lssl	使用時須要添加的編譯指令
@copyright	@copyright Apple	版權，這個值會覆蓋在配置文件中的值，同時不能被分爲多行
@CFBundleIdentifier	@CFBundleIdentifier org.mklinux.driver.test	所在的包名、程序的BundleID
@encoding	@encoding utf-8	爲生成的HTML文件設置編碼
@flag	@flag -lssl The SSL Library	參見@compilerflag
@ignore	@ignore API_EXPORT	告訴HeaderDoc刪除指定的標記
@ignorefuncmacro	@ignorefuncmacro __P	告訴HeaderDoc不要包含指定的方法宏
@language	@language c++	已經廢棄的tag。指定當前的開發語言
@meta	@meta robots index,nofollow 或者 @meta http-equiv="refresh" content="0;http://www.apple.com"	將要添加到每一個頁面的meta tag，能夠用這兩種形式中的一種指定 @meta 或 @meta ，可是不能分紅多行
@preprocinfo	@preprocinfo This header uses the DEBUG macro to enable additional debugging.	描述與processor相關的宏（-DDEBUG, for example)指定以後的行爲）
@related	@related Sixth cousin of Kevin Bacon.	指出與這個頭文件關聯的另外一個頭文件，可使用多個@related標籤
@unsorted	@unsorted	指出你不但願HeaderDoc幫你對頭文件的內容排序
@version	@version 2.3.1	文檔適用的版本
@whyinclude	@whyinclude Because it was there.	指出你爲何要包含一些頭文件