JSDoc
JSDocは、JavaScriptのソースコードにアノテーション(注釈)を追加するために使われるマークアップ言語である。JSDocをコメントの中に含めることで、プログラマーは自分が書いたコードのAPIを記述するドキュメントを追加することができる。JSDocをさまざまなツールで処理することで、HTMLやRich 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 IDEA、NetBeans、RubyMineは、JSDocの構文を認識することができる。
- Eclipse IDEには、JSDoc構文を認識できるようにする拡張機能がある。EclipseをベースにしたAptana StudioはScriptDocをサポートしており、含まれているJavaScriptファイルはScriptDocでコメントされている。
- MozillaのインラインエディタMozileは、JSDocを使用している。
- Helmaアプリケーションフレームワークは、JSDocを使用している。
- SproutCoreのドキュメンテーションは、JSDocから自動生成されている。[1]
- Visual StudioやWebStormなどの統合開発環境（IDE）やテキストエディタは、JSDocのコメントに基づいたコード補完機能などのコーディング支援機能を提供している。
- オープンソースのエディタAtomは、atom-easy-jsdocプラグインによりJSDocをサポートしている。
脚注
[編集]関連項目
[編集]外部リンク
[編集]- Use JSDoc: Index - JSDoc公式サイト。使用方法のチュートリアルとドキュメント
- GitHub - jsdoc/jsdoc: An API documentation generator for JavaScript. - JSDoc公式GitHub。最新のコードの公開場所
- "Annotating JavaScript for the Closure Compiler" - Google DeveloperウェブサイトにあるClosure Toolsのドキュメント
