HeadDoc自動註釋語法

時間  2019-11-17
標籤 headdoc 自動 註釋 語法 简体版
原文   原文鏈接

記錄於2013/4/23:

html

關於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
相關文章
相關標籤/搜索
每日一句
    每一个你不满意的现在，都有一个你没有努力的曾经。
本站公眾號
   歡迎關注本站公眾號,獲取更多信息
聯繫我們 最近搜索 最新文章 沪ICP备13005482号-10 MyBatis教程 SQL 教程 MySQL教程 Java 教程 Thymeleaf 教程 Hibernate教程 Spring教程 Redis教程