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 |
| @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. | 指出你为什么要包含一些头文件 |