🗂

[JavaScript]JSDOCについて

2022/10/04に公開約1,700字

JSDocとは

  • JSDocは、JavaScriptのソースコードにアノテーション(注釈)を追加するために使われるマークアップ言語。

なぜ使うか

1.複数人で開発を進める場合や、大規模なプログラムを開発する場合に、変数のデータ型やオブジェクトの種類(配列、関数、コンストラクタ、クラスなど)をコメントとして記述することで、他の人がそれらを見分けることができ、開発の効率が上がる。

2.JSDocに対応しているエディターを使うとかなり開発効率が上がる。JSDocに対応しているエディターVSCodeで、以下のように関数を作りJSDocをコメントとして書くと、別のファイルで関数にカーソルを合わせたときに、JSDocコメントが表示されます。

JSDocの書き方

  • "/"で初めて、"*/"で終わる。
  • その間に記述がある分だけ"*"を書く。
/**
 * [記述]
 */

変数

@typeの後の{}内に変数の型(String, Number, Boolean)を書き、そのあとに変数の説明を書く。

/**
 * @type {Number} 年齢
 */
const age = 25;

配列

@typeの後の{}内にArrayと書き、そのあとに配列の説明を書く。

/**
 * @type {Array} 年齢の配列
 */
const ageArray = [10, 22, 30];

連想配列

  • 最初に@typeで連想配列の説明を書く。連想配列はオブジェクトの扱いなので、{}の中はobjectと書く。
  • 次に連想配列のオブジェクト内の@typeで連想配列のペアが何を意味しているのかを書く。{}内は連想配列の値(value)の型を書く。
/**
 * @type {Object} 会員情報の連想配列
 */
const memberInfo = {
  /**
   * @type {Number} 会員番号
   */
  id: 1,
  /**
   * @type {String} 会員名
   */
  name: 'taro imo',
};

クラス(インスタンス)

  • はじめにクラス(インスタンス)の説明をする。
  • @constructorがコンストラクタであることを表す。(なくても良い)
  • @thisが何を指しているのか{}の中に書く。
  • @paramで関数の引数の説明を書く。{}の中には関数の引数の型を書く。
/**
 * Personクラスのインスタンスを作成する。
 * @constructor
 * @this {Person}
 * @param {String} name 名前
 * @param {Number} age 年齢
 */
const Person = function (name, age) {
  this.name = name;
  this.age = age;
};

const taroImo = new Person('taroImo', 23);
console.log(taroImo.name); // taroImo
console.log(taroImo.age); // 23

関数

  • まずコメントの最初に関数の説明を書く。
  • 次に@paramで関数の引数の説明を書く。{}の中には関数の引数の型を書く。
  • 最後に@returnで返り値の説明を書く。{}の中には返り値の型を書く。
  • *関数内の変数のJSDocは省いている。
/**
 * 10年後の年齢を返す
 * @param {Number} age 年齢
 * @return {Number} 10年後の年齢
 */
function tenYearsLater(age) {
  const tenYearsLater = age + 10;
  return tenYearsLater;
}

参考

https://qiita.com/tarotaro1129/items/c7b742f3602c7749a29d

Discussion

ログインするとコメントできます