JSDocは、JavaScriptソースコードにアノテーションを追加するために使われるマークアップ言語である。JSDocをコメントの中に含めることで、プログラマーは自分が書いたコードのAPIを記述するドキュメントを追加することができる。JSDocをさまざまなツールで処理することで、HTMLRich Text Formatなどの形式のアクセス可能なドキュメンテーションを自動生成することができる。JSDocは、Apache License 2.0の元にライセンスされている自由ソフトウェアである。

歴史 編集

JavaScriptをドキュメントするためにJavadocに似た構文を使用した最初期の使用例[要出典]は、1999にリリースされたNetscape/MozillaプロジェクトのRhinoである。これは、Javaで書かれたJavaScriptのランタイムシステムである[1]

JSDocの構文とセマンティックスは、Javaに書かれるコードのドキュメンティングに使われる、Javadocのスキームに似ている。JSDocがJavadocと異なるのは、JavaScriptの動的な振る舞いを扱うために特化している点である。

JSDocタグ 編集

モダンなJSDocでよく使用されるアノテーションの一部を紹介する。

タグ 説明
@author 開発者の名前
@constructor 関数がコンストラクタ(constructor)であるという印をつける
@deprecated 関数が非推奨(deprecated)であるという印をつける 
@exception @throwsの別名
@exports モジュールがexportするメンバーであることを指定する
@param メソッドのパラメータをドキュメント化する。波括弧の中にデータ型の名前を書いて、パラメータ名の前に挿入することができる。
@private メンバーがprivateであることを示す
@return 返り値をドキュメント化する
@returns @returnの別名
@see 他のオブジェクトとの関連をドキュメント化する
@todo 不足しているものや追加可能なもの(something open)をドキュメント化する
@this 関数内で"this"というキーワードが指しているオブジェクトの型を指定する
@throws メソッドが投げる例外をドキュメント化する
@version ライブラリのバージョンナンバーを提供する

編集

/**
 * Circle のインスタンスを作成する。
 *
 * @constructor
 * @author: わたし
 * @this {Circle}
 * @param {number} r 作成したい円の半径。
 */
function Circle(r) {
    /** @private */ this.radius = r;
    /** @private */ this.circumference = 2 * Math.PI * r;
}

/**
 * 直径から新しい Circle を作成する。
 *
 * @param {number} d 作りたい円の直径。
 * @return {Circle} 新しい Circle オブジェクト。
 */
Circle.fromDiameter = function (d) {
    return new Circle(d / 2);
};

/**
 * Circle の円周を計算する。
 *
 * @deprecated
 * @this {Circle}
 * @return {number} 円の円周。
 */
Circle.prototype.calculateCircumference = function () {
    return 2 * Math.PI * this.radius;
};

/**
 * Circle の計算済みの円周を返す。
 *
 * @this {Circle}
 * @return {number} 円の円周。
 */
Circle.prototype.getCircumference = function () {
    return this.circumference;
};

/**
 * Circle の文字列表記を返す。
 *
 * @override
 * @this {Circle}
 * @return {string} この Circle のヒューマンリーダブルな表記。
 */
Circle.prototype.toString = function () {
    return "A Circle object with radius of " + this.radius + ".";
};

JSDocの使用例 編集

  • GoogleのClosure LinterおよびClosure Compiler英語版。後者は、型情報を抽出することで、JavaScriptの出力を最適化する。
  • 有名なエディタSublime TextはJSDocをDocBlockrまたはDoxyDoxygenプラグインによってサポートする。
  • JSDocの構文は、次の書籍内に詳細に記述されている。Apress book Foundations of Ajax ISBN 1-59059-582-3
  • IntelliJ IDEANetBeansRubyMine英語版は、JSDocの構文を認識することができる。
  • Eclipse IDEには、JSDoc構文を認識できるようにする拡張機能がある。EclipseをベースにしたAptana Studio英語版はScriptDocをサポートしており、含まれているJavaScriptファイルはScriptDocでコメントされている。
  • MozillaのインラインエディタMozileは、JSDocを使用している。
  • Helmaアプリケーションフレームワークは、JSDocを使用している。
  • SproutCoreのドキュメンテーションは、JSDocから自動生成されている。[1]
  • Visual StudioWebStorm英語版などの統合開発環境(IDE)やテキストエディタは、JSDocのコメントに基づいたコード補完機能などのコーディング支援機能を提供している。
  • オープンソースのエディタAtomは、atom-easy-jsdocプラグインによりJSDocをサポートしている。

脚注 編集

  1. ^ jsdoc.js”. Mozilla project (1999年5月6日). 2013年4月15日時点のオリジナルよりアーカイブ。2018年9月30日閲覧。

関連項目 編集

外部リンク 編集