Eclipse和IntelliJ IDEA系的IDE都有自动生成文档注释的功能,Xcode虽然安装了VVDocument,但是仍然感觉注释的功能不是很完善,于是今天整理了一下书写文档注释的一些用法。 首先要说的就是文档注释提取的工具:主要是介绍HeaderDoc和appleDoc 1.我们平常长按option键同时鼠标点击,弹出的文档就是Xcode会自动使用HeaderDoc生成的。如图: quik look查看HeaderDoc生成的文档 2.appleDoc只为Objective-C服务,可以在文档书写完成之后使用appledoc生成docSet,能生成和Apple一个风格的文档,如下所示: appleDoc生成的docSet效果图 然后要说的就是一些编写文档注释的规范了:(注意本文值讨论文档注释,仅仅作为解释说明的注释不会涉及) #### 单行注释 共有以下几种: 行前注释:(功能较多,可用作对属性、方法、类的声明,通常用作对属性的声明)

///

行后注释:(一般对属性、成员变量的声明等)

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

使用的方法如下:

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