记录于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
•变量和常量的声明没有与他们相关联的特殊二级标签
@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：(结构、联合)
结构、联合、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:(枚举)
•唯一的特定与枚举的的标签是@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