正文

HeadDoc自动注释语法

IP云
IP云V管理员/0 阅读
08/30
小程序：扫一扫查出行
【扫一扫了解最新限行尾号】
复制小程序

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