「JSDoc」の版間の差分
削除された内容 追加された内容
Wiki stakahashi (会話 | 投稿記録) m 公式サイトへのリンクを修正 |
|||
| 57行目: | 57行目: | ||
== 例 == |
== 例 == |
||
< |
<syntaxhighlight lang="javascript"> |
||
/** |
/** |
||
* Circle のインスタンスを作成する。 |
* Circle のインスタンスを作成する。 |
||
| 112行目: | 112行目: | ||
return "A Circle object with radius of " + this.radius + "."; |
return "A Circle object with radius of " + this.radius + "."; |
||
}; |
}; |
||
</syntaxhighlight> |
|||
</source> |
|||
== JSDocの使用例 == |
== JSDocの使用例 == |
||
2020年7月5日 (日) 23:10時点における版
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公式サイト - 使用方法のチュートリアルとドキュメント
- JSDoc公式GitHub - 最新のコードの公開場所
- "Annotating JavaScript for the Closure Compiler" - Google DeveloperウェブサイトにあるClosure Toolsのドキュメント
