HeadDoc自动注释语法

记录于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

 

官方文档:

https://developer.apple.com/library/mac/#documentation/DeveloperTools/Conceptual/HeaderDoc/tags/tags.html%23//apple_ref/doc/uid/TP40001215-CH346-CHDJFEGF

---

---

 

 

 

但有些标签仅在特定的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