记录于2013/4/23:
关于HeaderDoc注释和标签的简要介绍
每个HeaderDoc注释可分为顶级标签和第二级标签：
（1）顶级标签：宣布API的声明类型 (function, struct, enum, 等等)，是可选择的。 也可为空
（2）第二级标签：给予声明的额外信息 如@abstract 指定抽象
(@abstract and @discussion) 为紧接顶级标签的两个第二级标签，是可择选的，但建议要有该字段
@abstract:用在摘要列表
@discussion: 用在详细文档中
•第二级标签根据其行为可进一步细分为以下几类：
attribute - 一个标签内容出现在属性列表的行中，该标签直到下一个block或则attribute标签出现为止。
block - 包含多个文字段落，通常显示为一个正常的文本块(通常是标题开头).该标签直到下一个block或则attribute标签出现为止。
flag - 修改一个标签声明的行为，包括是否发出它在某些情况下(例如：@parseOnly)。标志标签不带任何参数。
HTML tagging - 影响HTML标记，而不是直接作为输出的一部分发出。
inline - 一个标签可以出现在一个段落里面大多数标签(名称或标题字段除外)。内嵌标签的内容不会破坏文本流。
page footer - 一个标签，出现在页脚中的每个内容页底部的修改内容 (例如:@copyright)
parsing - 修改源代码文件解析的方式
term & definition - 根据该标签包含的内容行数分成第一行或则换行两部分，区分规则和顶端标签一样，规则在“Multiword Names”定义。
•在HeaderDoc 8.6之后的版本中，第二级标签可以出现在HeaderDoc注释的任意位置，但是以下三个是例外：
@const, @constant, and @var
这些tag不能出现在一个HeaderDoc注释的开头，因为它们与顶级标签相冲突 HeaderDoc一些变种注释风格。特别是，你可以有这样一行注释：
/*! @var settle_time Latency before next read. */
•可以在一个多行注释前添加星号（但必须保持一致性）
| |
| @function HMBalloonRect |
| @abstract Reports size and location of help ballon. |
| @discussion Use HMBalloonRect to get information about the size of a help balloon |
| before the Help Manager displays it. |
| @param inMessage The help message for the help balloon. |
| @param outRect The coordinates of the rectangle that encloses the help message. |
| The upper-left corner of the rectangle has the coordinates (0,0). |
| */ |
• 如果想要换行显示discussion，则需要键入两次换行健，即中间要空一行；这样就可以分两行显示
| |
| * @function HMBalloonRect |
| * @discussion Use HMBalloonRect to get information about the size of a help balloon |
| * before the Help Manager displays it. |
| |
| * Always check the help balloon size before display. |
| |
Multiword Names:
复名(多文字名称): 顶层标记(如@header and @function等)可采用多个字的名称，但是通常HeaderDoc无法判断是多字名称还是discussion
自动标注：
（1）Numbered lists：它不再是必要的标记编号列表<OL> <LI>。 HeaderDoc会自动检测编号列表。
（2）像@function, @class, and @typedef 这样的声明类型的标签在HeaderDoc 8以后会自动添加，不需要声明，除非你试图到覆盖HeaderDoc的正常行为。
（3）可用性宏(Availability macros)：它不再是必要利用@ignore忽略可用性宏
所有HeaderDoc注释类型的通用标签
可用在任何数据类型、函数、头文件或则类中 。
下面仅列出较为常用的几个标签；其他标签可到官方文档中查看；
| Tag | Example | Identifies | Usage |
| @abstract | @abstract write the track to disk | 一个简短的字符串简要描述一个函数，数据类型等等，只能为1行。保存discussion的详细说明 | block (single short sentence recommended) |
| @availability | @availability 10.3 and later | 一个字符串描述函数、类等等的可用性 | attribute |
| @discussion | @discussion This is what this function does. @some_other_tag | 一个文本块，详细描述一个函数，类，标题，或数据类型；它即可包含多个字断也可省略；但是如果你的数据类型、函数、类或头名中存在多个字段，则改文本块就必须存在；该文本块仅在另一个标签开始时才结束 | block |
| @namespace | @namespace BSD Kernel | 一个字符串描述函数、数据类型等所存在的命名空间 | attribute |
| @updated | @updated 2003-03-14 | header的更新时间 | attribute |
官方文档:
但有些标签仅在特定的context中才有效：
Functions, Methods, and Callbacks：(函数、方法和回调)
顶端标签：@function, @method, @callback
@function用于C函数，而
@method用于Objective-C方法，这两个可以互换 | Tag | Example | Identifies | Type |
| @param | @param myValue The value to process. | 描述函数或回调的参数 | attribute (term & definition) |
| @result | @result Returns 1 on success, 0 on failure.. | 描述该函数返回的值，如果函数类型是void或者OSERR则不写该标签 | attribute (term & definition) |
| @return | @return Returns 1 on success, 0 on failure.. | 同上 | attribute (term & definition) |
| @throws | @throws bananas | 该函数的每个异常抛出都包含一个@throws标签(如果支持异常) | attribute |
| @var | @var myVar Description goes here | 标记一个函数或方法的局部变量； 注意：不能作为函数或者方法的顶端标签 | Term & definition |
Constants and Variables：(常量和变量)
顶端标签：@var, @const, @constant
•@var: 在标记全局变量、类变量、实例变量时会被用到(而不是声明新的数据类型或宏)
•常量被标记为:@const 或者 @constant
•变量和常量的声明没有与他们相关联的特殊二级标签
@const标签使用例子：
| |
| @const kCFTypeArrayCallBacks |
| @abstract Predefined CFArrayCallBacks structure containing a set of callbacks appropriate... |
| @discussion Extended discussion goes here. |
| Lorem ipsum.... |
| */ |
| const CFArrayCallBacks kCFTypeArrayCallBacks; |
@var标签使用例子：
| |
| @var we_are_root |
| @abstract Tells whether this device is the root power domain |
| @discussion TRUE if this device is the root power domain. |
| For more information on power domains.... |
| */ |
| bool we_are_root; |
Properties：(属性)
顶端标签：@property
•它支持@method 和 @var 所支持的任一标签
•注意：JavaScript属性应该被标记为普通变量。
Structures and Unions：(结构、联合)
顶端标签：@struct, @union, @typedef
结构、联合、typedef声明所包含的结构、联合可以包含回调(callbacks)和字段(fields)。
相应的第二级标签描述如下:
| Tag | Example | Identifies | Type |
| @callback | @callback testFunc The test function to call. | 指定结构中的一个回调字段的名称和描述 | attribute (term & definition) |
| @field | @field isOpen Specifies whether the file descriptor is open. | 结构声明中的一个字段 | attribute (term & definition) |
@struct的使用例子：
| |
| @struct TableOrigin |
| @abstract Locates lower-left corner of table in screen coordinates. |
| @field x Point on horizontal axis. |
| @field y Point on vertical axis |
| @discussion Extended discussion goes here. |
| Lorem ipsum.... |
| |
| struct TableOrigin { |
| int x; |
| int y; |
| } |
Enumerations:(枚举)
顶端标签：@enum, @typedef
•唯一的特定与枚举的的标签是@const 和 @constant; | Tag | Example | Identifies | Type |
| @constant @const | @const kSilly A silly return value. | 枚举中的常量 | attribute (term & definition) enum declarations only |
(1)枚举的使用例子:
| |
| @abstract Categorizes beverages into groups of similar types. |
| @constant kSoda Sweet, carbonated, non-alcoholic beverages. |
| @constant kBeer Light, grain-based, alcoholic beverages. |
| @discussion Extended discussion goes here. |
| Lorem ipsum.... |
| |
| enum beverages { |
| kSoda = (1 << 6), |
| kBeer = (1 << 7) |
| }; |
(2)匿名枚举的使用例子()
| |
| @enum Beverage Categories |
| @abstract Categorizes beverages into groups of similar types. |
| @constant kMilk Dairy beverages. |
| @constant kWater Unflavored, non-sweet, non-caloric, non-alcoholic beverages. |
| @discussion Extended discussion goes here. |
| Lorem ipsum.... |
| |
| enum { |
| kMilk = (1 << 8), |
| kWater = (1 << 9) |
| }; |
Type Definitions:(类型定义)
顶端标签：@typedef
•根据@typedef声明的内容决定可在@typedef标签后显示的标签；例如:一个typedef enum声明拥有enum声明所包含的任何内容。
•一个@typedef命令可以包括以下任何一个：
(1)typedef struct 声明中的@field(字段)
(2)typedef enum 声明中的@constant(常量)
(3)单独函数指针类型的typedef声明中的@param(参数)
(1)typedef struct用例:
| |
| @typedef TypedefdSimpleStruct |
| @abstract Abstract for this API. |
| @field firstField Description of first field |
| @field secondField Description of second field |
| @discussion Discussion that applies to the entire typedef'd simple struct. |
| Lorem ipsum.... |
| |
| typedef struct _structTag { |
| short firstField; |
| unsigned long secondField |
| } TypedefdSimpleStruct; |
(2)typedef enum用例：
| |
| @typedef TypedefdEnum |
| @abstract Abstract for this API. |
| @constant kCFCompareLessThan Description of first constant. |
| @constant kCFCompareEqualTo Description of second constant. |
| @constant kCFCompareGreaterThan Description of third constant. |
| @discussion Discussion that applies to the entire typedef'd enum. |
| Lorem ipsum.... |
| |
| typedef enum { |
| kCFCompareLessThan = -1, |
| kCFCompareEqualTo = 0, |
| kCFCompareGreaterThan = 1 |
| } TypedefdEnum; |
(3)函数指针的typedef用例:
| |
| @typedef simpleCallback |
| @abstract Abstract for this API. |
| @param inFirstParameter Description of the callback's first parameter. |
| @param outSecondParameter Description of the callback's second parameter. |
| @result Returns what it can when it is possible to do so. |
| @discussion Discussion that applies to the entire callback. |
| Lorem ipsum... |
| */ |
| typedef long (*simpleCallback)(short inFirstParameter, unsigned long long *outSecondParameter); |
常用注释示例:
/*!
@header
@abstract 摘要描述
@discussion 详细描述
@namespace 命名区间
@updated 2013-02-21
@author 作者
@version 版本信息
*/
#import <UIKit/UIKit.h>
#import "NSData+extend.h"
/*!
@enum
@abstract 摘要描述
@discussion 详细描述
@constant const1 常量1
@constant const2 常量2
*/
typedefenum
{
const1 = 1,
const2 = 2
}Status;
/*!
@protocol
@abstract 摘要描述
@discussion 详细描述
@namespace 命名区间
@updated 2013-02-21
*/
@protocol ViewDelegate <NSObject>
@end
/*!
@class
@abstract 摘要描述
@discussion 详细描述
*/
@interface ViewController : UIViewController{
/*! UITableView成员变量. */
UITableView *tableView;
}
/*! @var settleString NSString成员变量. */
@property (nonatomic,retain) NSString *string;
/*!
@method
@abstract 摘要描述
@discussion 详细描述
@param sender 参数1 (这里把这个方法需要的参数列出来)
@param idSender 参数2
@return string 字符串
*/
-(NSString *)btnClicked:(UIButton *)sender AndID:(id)idSender;
@end
/*!
@category
@abstractNSData的Category
*/
@interfaceNSData (extend)
@end