记录于2013/4/23:
html
这些tag不能出如今一个HeaderDoc
注释的开头,由于它们与顶级标签相冲突
|
@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).
|
*/
|
|
* @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.
|
|
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
|
@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
|
|
@const kCFTypeArrayCallBacks
|
@abstract Predefined CFArrayCallBacks structure containing a set of callbacks appropriate...
|
@discussion Extended discussion goes here.
|
Lorem ipsum....
|
*/
|
const CFArrayCallBacks kCFTypeArrayCallBacks;
|
|
@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;
|
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 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;
|
}
|
•惟一的特定与枚举的的标签是@const 和 @constant;
Tag
|
Example
|
Identifies
|
Type
|
@constant
@const
|
@const kSilly A silly return value.
|
枚举中的常量
|
attribute (term & definition)
enum declarations only
|
|
@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)
|
};
|
|
@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)
|
};
|
|
@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;
|
|
@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;
|
|
@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);
|