JSDoc

JSDocとは

JSDocは、JavaScriptのソースコードにアノテーション（注釈）を記述するためのマークアップ言語です。コード内にJSDoc形式のコメントを追加することで、プログラマーは自身のコードのAPIに関するドキュメントを作成できます。これらのコメントは、様々なツールによって処理され、HTMLやリッチテキスト形式などのドキュメントを自動生成するために利用されます。JSDocは、Apache License 2.0 の下でライセンスされているフリーソフトウェアです。

歴史

JavaScriptのドキュメント作成にJavadocに似た構文が初めて使用されたのは、1999年にリリースされたNetscape/MozillaプロジェクトのRhinoです。これは、Javaで記述されたJavaScriptのランタイムシステムでした。

JSDocの構文とセマンティクスは、Javaで記述されたコードのドキュメント化に使用されるJavadocのスキームに類似しています。JSDocがJavadocと異なるのは、JavaScriptの動的な性質を扱うために特化している点です。

JSDocタグ

現代的なJSDocで使用される一般的なアノテーションには、以下のようなものがあります。

`@param`：関数やメソッドの引数を記述します。
`@returns`：関数やメソッドの戻り値を記述します。
`@typedef`：カスタムデータ型を定義します。
`@property`：オブジェクトのプロパティを記述します。
`@class`：クラスを記述します。
`@constructor`：コンストラクタを記述します。
`@extends`：クラスの継承関係を記述します。
`@private`：非公開のメンバーであることを示します。
`@public`：公開されているメンバーであることを示します。
`@deprecated`：非推奨のAPIであることを示します。

JSDocの使用例

JSDocは、様々なツールや環境で使用されています。

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

もう一度検索