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および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をサポートしている。

関連かんれん項目こうもく

• ドキュメンテーションジェネレータの比較ひかく
• 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のドキュメント