アノテーションの書き方
JsDoc アノテーションとは
JsDocはソースコードを解析します。
しかし、引数の意味やクラスの意味などはソースコードから読み取ることはできません。
そこで、ソースコードからだけでは得られない情報をアノテーション（注釈）という形で記述することで JsDoc に通知してやります。
/**
* ほげほげなクラス。
* @constructor
* @param {number} hoge 「ほげ」の出力回数。
*/
function HogePrinter(hoge) {
this.hoge = hoge;
}
/** * ほげほげを出力するメソッド。
* @param {number} [num] ほげほげ回数。省略可能。
* @return {string} ほげほげ文字列。
*/
HogePrinter.prototype.print = function(num) {
var hoges = [];
for (var i = 0, l = num || this.hoge; i < l; i++) {
hoges.push('hoge');
}
return hoges.join('');
};
上の例の /** ... */ で囲まれた部分が JsDoc アノテーションです。
ドキュメントに落としたいオブジェクトの直前に JsDoc アノテーションを記述します。
JsDoc アノテーションの書き方
JsDocアノテーションにはいくつかのパターンがありますが、どれも同様に解釈されます。
パターン1
/**
* ほげほげを出力するメソッド。
* @param {number} [num] ほげほげ回数。省略可能。
* @return {string} ほげほげ文字列。
*/
HogePrinter.prototype.print = function(num) {
パターン2
/** ほげほげを出力するメソッド。
@param {number} [num] ほげほげ回数。省略可能。
@return {string} ほげほげ文字列。
*/
HogePrinter.prototype.print = function(num) {
パターン3 (1ライナー)
/** ほげほげを出力するメソッド。*/ HogePrinter.prototype.print = function(num) {
特に理由がなければ、Closure Libraryとの親和性が高いパターン１がお勧めです。
タグの書き方
JsDoc アノテーションではタグで情報を記述していきます。タグは @... のように記述され、基本的には一行に一タグです。
/**
* ほげほげを出力するメソッド。
* @param {number} [num] ほげほげ回数。省略可能。
* @return {string} ほげほげ文字列。
*/ HogePrinter.prototype.print = function(num) {
上の例では、 @param と @return がタグです（一番上の行は @desc が省略されています）。
JsDoc には様々なタグがあります。
主要属性
@param @return @extends
アクセス識別子
@private @protected @public @access
オブジェクト属性
@class @constructor @function @constant @member @enum ...
オブジェクト参照属性
@static @inner
説明
@desc @example @fileoverview @classdesc ...
サポート情報
@version @since @deprecated @see @author
文章修飾
{@code sampleCode} {@link http://exmaple.com} HTML要素 <ul> <ol> <dl> <li> <dt> <dd> <pre> <code>
などがあります。詳しくはタグリファレンスを参照してください。
アノテーションの方針
アノテーションの内容の充実度については加減が必要です。
タグが少なすぎても後から読めなくなるし、多すぎると作業が繁雑になります。
特に長期にわたる、あるいは大規模な開発ではアノテーションの記述・変更も多くなるため保守の負担は馬鹿になりません。
自分が継続できると思うアノテーションの充実度を見つけることが重要です。
OrgaChemの私見
あなたがライブラリの作者であれば、いかに作業が繁雑であろうと多くのタグをつけるほうがよいでしょう。
そうでないのであれば、Closure Compiler が求めているタグ： @param @return @extends @private @constructor @this @fileoverview @author が記述されている程度で良いのでないでしょうか。