JSDoc

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

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

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

脚注

JSDoc

Źródło i licencja