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