JSDocについての備忘録

JSDocの事を今更知ったので、個人的な備忘録として書き残しておきます。

## ただのコメント？
最初に見たときは**ただの行数が長いコメント**としか思っておりませんでした。
どうやらJSDocというらしいと知ったのはつい最近です。

## 何のためにある？
- **コードのドキュメンテーション:** 関数、変数、クラスなどの要素に対して、その役割、引数、戻り値、使用例などを詳細に記述することができます。これにより、コードを読む人がその部分の機能を素早く理解できるようになり、開発効率が向上します。
- **静的型チェック:** TypeScriptのような静的型付け言語ではないJavaScriptにおいて、JSDocを利用することで、変数の型や関数の引数・戻り値の型を明示的に指定することができます。これにより、開発中に型に関するエラーを早期に検出し、バグを減らすことができます。
- **自動ドキュメント生成:** JSDocで記述されたコメント情報を基に、自動的にAPIドキュメントを生成するツールがあります。これにより、チームで開発を行う際や、外部にライブラリを公開する際に、高品質なドキュメントを簡単に作成できます。
- **コードの理解促進:** 特に大規模なプロジェクトや、自分が書いたコードをしばらく後に見返したい場合、JSDocによってコードの意図が明確になり、よりスムーズに理解することができます。



:::note warn
上記は例によってAIに聞いてみた結果です。
:::

## 書き方

[Google JavaScript スタイルガイド - 日本語訳](https://w.atwiki.jp/aias-jsstyleguide2/pages/14.html)には、書き方の注意が以下のように書かれています。

> 全てのファイル、クラス、メソッド、プロパティにJSDocコメントが、適切なタグとデータ型を伴って記されるべきです。また名前から明白に判断できる場合を除き、プロパティ、メソッド、メソッドの引数、メソッドの戻り値を説明する文章が含まれているべきです。
完全文（Complete sentence）で書くことを推奨しますが、必須ではありません。完全文を使う場合は適切に大文字で開始し、句読点で終わらせましょう。

```javascript
/**
 * JSDocコメントはスラッシュと2つのアスタリスクから始めます。
 * インラインタグは {@code this} のように波括弧で囲みます。
 * @desc ブロックタグは必ず行の先頭から開始します。
 */
```

上記の書き方もGoogle JavaScript スタイルガイドから引用しています。



## 使用頻度の高いタグ 

JSDocは様々なタグが用意されていますが、特に使用頻度が高いのは以下のタグのようです。
コード内容はJSDocの公式から持ってきています。

### [@param](https://jsdoc.app/tags-param) 
関数パラメータの名前、タイプ、および説明を記述します。
説明を記述する場合は、説明の前にハイフンを挿入することで、JSDoc コメントを読みやすくすることができます。
ハイフンの前後には必ずスペースを入れる必要があるようです。


```javascript
/**
 * @param {string} somebody - Somebody's name.
 */
function sayHello(somebody) {
    alert('Hello ' + somebody);
}
```

### [@returns](https://jsdoc.app/tags-returns)
関数の返り値を記述します。

```javascript
/**
 * Returns the sum of a and b
 * @param {number} a
 * @param {number} b
 * @returns {number}
 */
function sum(a, b) {
    return a + b;
}
```


### [@type](https://jsdoc.app/tags-type)
変数やプロパティのデータ型を記述します。

```javascript
/** @type {(string|Array.<string>)} */
var foo;
/** @type {number} */
var bar = 1;
```

### [@typedef](https://jsdoc.app/tags-typedef)
定義されたカスタム型を記述します。

```javascript
/**
 * @typedef {Object} User
 * @property {number} id - User's ID.
 * @property {string} name - User's name.
 */

/** @type {User} */
var user = {
    id: 1,
    name: "Alice"
};

```

### [@description](https://jsdoc.app/tags-description)

詳細な説明を記述します。
他のタグと組み合わせて使われることが多いです。

```javascript
/**
 * @param {number} a
 * @param {number} b
 * @returns {number}
 * @description Add two numbers.
 */
function add(a, b) {
    return a + b;
}
```

### [@example](https://jsdoc.app/tags-example)
具体的なコード例を記述するときに使用します。

```javascript
/**
 * 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](https://jsdoc.app/tags-deprecated)
非推奨の機能やメソッドを記述します。

```javascript
/**
 * @deprecated since version 2.0
 */
function old() {
}
```


### [@see](https://jsdoc.app/tags-see)
関連情報や参考リンクを記述します。
関連する公式ドキュメントやリファレンスページへのリンクを記述することで、わざわざ検索するリソースを確保できたりしそうです。

```javascript
/**
 * 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](https://jsdoc.app/tags-throws)
関数やメソッドが特定の状況で例外をスローする場合に、その例外の説明を提供するために使用されます。


```javascript
/**
 * @throws {InvalidArgumentException}
 */
function foo(x) {}
```

「スローする」ってなんだよって思ってググったら以下が分かりやすかったです。

https://mond.how/topics/12okosled1w22qy

### おまけ
実際に書いてある例を見てみたいので、Github Copilotにお願いしてみました。

![スクリーンショット 2024-12-15 21.28.20.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/3443/877430ff-6746-16e4-1337-8a3bae0c6021.png)

**Github Copilotめちゃめちゃ便利！！！**

## 参考

https://jsdoc.app/

https://ics.media/entry/6789/

https://www.typescriptlang.org/ja/docs/handbook/jsdoc-supported-types.html

https://zenn.dev/qnighy/articles/56917d9bf9077b

https://zenn.dev/azukiazusa/articles/c89d4bdc7dacf2