node.js+JSDoc3によるインラインAPIドキュメントの生成

謝辞

以下の記事を参考にさせていただきました。感謝です。

今回は「JavaScriptでコメントを書くときどうすればいいんだ？」という疑問から出発しました。 Javaだと、JavaDocの形式で書いておけば、Eclipse等のIDEを使うと対象のメソッドをわざわざ見に行かなくともコメント、引数、戻り値が見れて便利です。

またJavaScriptの場合、静的型付け言語のように型システムによる補助が受けられないので、個人的にものぐさからJavaScriptでいい感じにコメント・ドキュメンテーションが残せるものを調べました。

ドキュメント生成ルーツは色々あるようですが、今回はJSDoc3を使いました。

現状だとJSDocの後継”JsDoc Toolkit”がメジャーなようですが、さらに後継のJSDoc3を使いました。

JSDoc3をインストールします。 npmが既にインストールされている前提で

npm install -g git://github.com/jsdoc3/jsdoc.git

npmはとても便利ですね

ドキュメントに落としたいオブジェクトの直前にJSDocアノテーションを追加します。 Javaと同じく”/＊＊… ＊/ “で囲まれた部分がアノテーションとなります。

タグは、”＠… “で記述します。

実際にnode.js＋expressのコードにアノテーションを追加してみました。

上記のサンプルでは@param, @return, @moduleの3種類しか使っていませんが、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

JSDocを実行して、ドキュメントを生成します。

jsdoc app.js