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をサポートしている。
脚注
- ^ “jsdoc.js”. Mozilla project (May 6, 1999). April 15, 2013時点のオリジナルよりアーカイブ。2018年9月30日閲覧。
関連項目
- ドキュメンテーションジェネレータの比較(英語版)
- Google Closure Tools
外部リンク
- 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のドキュメント
| |
---|---|
| |
|
| |
---|---|
概念 |
|
エンジン | |
コンパイラ | |
デバッガ | |
エディタ | |
サーバーサイド |
|
フレームワーク・ライブラリ | |
ユニットテスト |
|
Docジェネレータ |
|
コード解析 | |
パッケージ管理 |
|
アプリケーションバンドラー | |
関連技術 | |
人物 | |
|