JSDoc をやっと真面目に使ってみた。実際に使ってみてハマったところを取り上げていく。基本的な使い方は自分で調べるなり試行錯誤するべし。

なお、以下はバージョン 1.9.9.2 について書いている。時間の経過とともにおかしな内容になっていく可能性大なので注意されたし。あと日本語のコメントは試してないんでどうなるか知らない。

正しく書く

値を取る attribute で値を書いてない¹など、構文的に正しくないときに、よく HTML::Template の方でエラーを吐いて止まる。phpDocumentor みたいにエラーレポートは作ってくれないし、HTML::Template 段階でのエラーってことは当然パーサが吐いてるわけはなく、どこの何の記述（あるいは記述不足）がエラーなのかさっぱり分からないので、あとでまとめてドキュメントを生成するのではなく、こまめに作るようにした方がよさげ。

書き方は JSDoc のサイトにもあるけど、細かいものは JavaDoc のものを探してくるといい感じかも。

コンストラクタの書き方

きちっと対応しているのは

function Object() {
  ..
}

のみっぽい。

var Object = new function() {
  return function() {
  };
};

はコンストラクタは解釈できるが、中のメンバ変数（JSDoc の出力では Field ってやつ）が解釈できなかった。

あとこのコンストラクタ関数のコメントの中に @constructor を書いておいた方がよい。書かないと Field の解釈に失敗しやすいみたい。

フィールド（メンバ変数）の書き方

JavaScript 的には単にコンストラクタで初期化されるプロパティなんだと思うんだけど、まぁ要するに

function Constructor() {
  this.prop1 = 'foo';
  this.prop2 = undefind;
  this.prop3;
}

のところ。中身のない状態で初期化するのは 3 ではなく 2 の方法、つまり明示的に undefined をセットする方法が正しい。JSDoc 的には。

明示してないものは Field Summary にも当然 Field Detail にも現れない。

メソッドにも @type を

@return に型を書いてもメソッドの型としては認識してくれない。ちょっと面倒だけど、

/**
 * @type   boolean
 * @return boolean
 */
method: function() {
}

にしないといけない。まぁ気にしなきゃいいって話もあるかもしんないけど、それだと Method Summary のところで戻り値の型が分からないのよね。

うっかり : が書けない。

/**
 * summary
 *
 * detail: foo bar hoge
 */
method: function() {
}

てなことをすると

detail: foo

の部分が

Class.prototype.detail = foo;

に展開され、結果として

Class.prototype.detail = foo;bar hoge

になる。

※ ただ、必ずなるかというとそうでない場合もある。よく分からん。

組み込みオブジェクトの拡張には @addon

@member を書くと二重に出力されるのでうざい。例えば以下のような感じ。

/**
 * @addon
 */
Array.prototype.include = function() {
}

ただ、ないとエラーになっていたような気がしていたのに、なくてもそのまま通ったりもする。あっれ？

メソッドの書き方

できないと思っていたが、

Class.prototype = {
  method: function() {
  }
}

の書き方も

Class.prototype.method = function() {
}

の書き方も両方いけた。

夜中は嘘書いてごめんなさい。

感想として

JavaScript の構文解釈の精度は意外と悪くないと言ったら失礼だけど、自分の書き方だとほぼ思った通りに解釈してくれる。ただそのうえでコメントの記述がその後押しをしていて、正しくコメント付けするとよりよいドキュメントが生成できる、という感じ。まぁコメント付けは正しい方がいいのは言うまでもないことなんだけど、phpDocumentor のエラーレポートみたいなものは期待できないので、若干人間の側の負荷が高いかなって気はする。

あと、こまめにドキュメント生成しろって辺りか。複数のファイルを一気に処理するとどこでおかしなことになってるのかなかなか分からないんで。

最後に、これは使えると思う。