書き方がいくつかあるときはTypeScript寄りの記法を選ぶ。
- 仮引数記述 @param {型} 名前 - 説明
- 戻り値記述 @returns {型}
- asyncな関数の戻り値 @returns {Promise<型>}
- 配列型 Array<型>
- 連想配列型 { [key: キーの型]: バリューの型 } TypeScriptと同じに書ける、ほんとかな？
- 連想配列 {"foo": "hoge", "bar": 100, [key: string]: number} 、型は波括弧で囲うので、二重の波括弧になるかも。ほんとかな？
- ユニオンは |
- nullableな型は ?型
- non-nuullableな型は !型
- typedef の例 @typedef {(number|string)} NumOrStr
- Object型の定義は @typedef {Object} typeName の後の @property 定義を続ける。
使ってみて事実と違ったら修正しよう。
注目すべきドキュメンテーションタグ：
- @namaespace
- @mixin, @mixes
- @callback
- @typedef, @property
型定義の事例：
/** * @file 人物情報の記述 * */ /** 計算用の関数の型 * @callback calcFn * @param {string} arg - 引数は文字列 * @returns {number} 年齢 */ /** 人物の型 * @typedef Person * @property {string} firstName - 名前 * @property {string} lastName - 名字 * @property {string} birthDate - 生年月日を表す文字列 * @property {calcFn} calcAge - 年齢を計算 */ /* end of file */
- ドキュメンテーションコメントだけのファイルでもOK
- 期待通りの型情報が出る。
- @property {function} fooo はOK
- @perperty { function(string, boolean) : number } foo はダメ。解釈できない。
- @perperty { (a:string, b:boolean) =>number} bar もダメ。
- @property {string | number} id - ID はなぜかOK
より詳しくは https://jsdoc.app/tags-type.html 。jsdoc ではなくて tsc なら関数型／アロー型も解釈できる → https://www.typescriptlang.org/ja/docs/handbook/jsdoc-supported-types.html 。が、ドキュメンテーションだからjsdocが解釈できないとしょうがない。
ハマリ所／落し穴
JsDoc構文の @enum は型が一定のオブジェクト＝マップ型＝ディクショナリ型を表す。TypeScriptのenumとは違う。
値が number である書き換えないマップ型は `@readonly @enum {number}` でアノテーションする。
/** * Enum for tri-state values. * @readonly * @enum {number} */ var triState = { /** The true value */ TRUE: 1, FALSE: -1, /** @type {boolean} */ MAYBE: true };
