JSDocの事を今更知ったので、個人的な備忘録として書き残しておきます。
ただのコメント？
最初に見たときはただの行数が長いコメントとしか思っておりませんでした。
どうやらJSDocというらしいと知ったのはつい最近です。
何のためにある？
- コードのドキュメンテーション: 関数、変数、クラスなどの要素に対して、その役割、引数、戻り値、使用例などを詳細に記述することができます。これにより、コードを読む人がその部分の機能を素早く理解できるようになり、開発効率が向上します。
- 静的型チェック: TypeScriptのような静的型付け言語ではないJavaScriptにおいて、JSDocを利用することで、変数の型や関数の引数・戻り値の型を明示的に指定することができます。これにより、開発中に型に関するエラーを早期に検出し、バグを減らすことができます。
- 自動ドキュメント生成: JSDocで記述されたコメント情報を基に、自動的にAPIドキュメントを生成するツールがあります。これにより、チームで開発を行う際や、外部にライブラリを公開する際に、高品質なドキュメントを簡単に作成できます。
- コードの理解促進: 特に大規模なプロジェクトや、自分が書いたコードをしばらく後に見返したい場合、JSDocによってコードの意図が明確になり、よりスムーズに理解することができます。
上記は例によってAIに聞いてみた結果です。
書き方
Google JavaScript スタイルガイド - 日本語訳には、書き方の注意が以下のように書かれています。
全てのファイル、クラス、メソッド、プロパティにJSDocコメントが、適切なタグとデータ型を伴って記されるべきです。また名前から明白に判断できる場合を除き、プロパティ、メソッド、メソッドの引数、メソッドの戻り値を説明する文章が含まれているべきです。
完全文（Complete sentence）で書くことを推奨しますが、必須ではありません。完全文を使う場合は適切に大文字で開始し、句読点で終わらせましょう。
/**
* JSDocコメントはスラッシュと2つのアスタリスクから始めます。
* インラインタグは {@code this} のように波括弧で囲みます。
* @desc ブロックタグは必ず行の先頭から開始します。
*/
上記の書き方もGoogle JavaScript スタイルガイドから引用しています。
使用頻度の高いタグ
JSDocは様々なタグが用意されていますが、特に使用頻度が高いのは以下のタグのようです。
コード内容はJSDocの公式から持ってきています。
@param
関数パラメータの名前、タイプ、および説明を記述します。
説明を記述する場合は、説明の前にハイフンを挿入することで、JSDoc コメントを読みやすくすることができます。
ハイフンの前後には必ずスペースを入れる必要があるようです。
/**
* @param {string} somebody - Somebody's name.
*/
function sayHello(somebody) {
alert('Hello ' + somebody);
}
@returns
関数の返り値を記述します。
/**
* Returns the sum of a and b
* @param {number} a
* @param {number} b
* @returns {number}
*/
function sum(a, b) {
return a + b;
}
@type
変数やプロパティのデータ型を記述します。
/** @type {(string|Array.<string>)} */
var foo;
/** @type {number} */
var bar = 1;
@typedef
定義されたカスタム型を記述します。
/**
* @typedef {Object} User
* @property {number} id - User's ID.
* @property {string} name - User's name.
*/
/** @type {User} */
var user = {
id: 1,
name: "Alice"
};
@description
詳細な説明を記述します。
他のタグと組み合わせて使われることが多いです。
/**
* @param {number} a
* @param {number} b
* @returns {number}
* @description Add two numbers.
*/
function add(a, b) {
return a + b;
}
@example
具体的なコード例を記述するときに使用します。
/**
* Solves equations of the form a * x = b
* @example
* // returns 2
* globalNS.method1(5, 10);
* @example
* // returns 3
* globalNS.method(5, 15);
* @returns {Number} Returns the value of x for the equation.
*/
globalNS.method1 = function (a, b) {
return b / a;
};
@deprecated
非推奨の機能やメソッドを記述します。
/**
* @deprecated since version 2.0
*/
function old() {
}
@see
関連情報や参考リンクを記述します。
関連する公式ドキュメントやリファレンスページへのリンクを記述することで、わざわざ検索するリソースを確保できたりしそうです。
/**
* Both of these will link to the bar function.
* @see {@link bar}
* @see bar
*/
function foo() {}
// Use the inline {@link} tag to include a link within a free-form description.
/**
* @see {@link foo} for further information.
* @see {@link http://github.com|GitHub}
*/
function bar() {}
@throws
関数やメソッドが特定の状況で例外をスローする場合に、その例外の説明を提供するために使用されます。
/**
* @throws {InvalidArgumentException}
*/
function foo(x) {}
「スローする」ってなんだよって思ってググったら以下が分かりやすかったです。
おまけ
実際に書いてある例を見てみたいので、Github Copilotにお願いしてみました。
Github Copilotめちゃめちゃ便利！！！
参考