プログラムを読みやすくするJSDocのコメントを覚える

プログラムを読みやすいものにするためJSDocのコメントを覚えます。

JSDocとは

定義された形式でコメントを書くすることでAPIをドキュメント化してくれます。今回はJSDocのコメントの書き方を覚えます。アノテーション(注釈)とも書かれています。

JSDocのコメントの書き方

JSDocのコメントは/**から始まり*/で終わります。

JSDocのシンプルな書き方

/** これはfooの説明です */
function foo() {
 // do someting...
}

上記は説明だけのとてもシンプルな書き方です。

JSDocのタグを使った書き方

JSDocにはタグがありコメント内で使用できます。タグは@から始まります。例えばコンストラクタを表す@constructorや引数の@param、返す値を表す@returnなどがあります。たくさんあるので今回は一部のみ使用します。

/**
 * 本を表します
 * @constructor
 */
function Book() {
  // do someting...
}

上記はコンストラクターであることを表しています。タグは原則1行に1つです。

/**
 * 本を表します
 * @constructor
 * @param {string} title - 本のタイトル
 * @param {string} author - 本の著者
 */
function Book(title, author) {
  // do someting...
}

上記は引数の説明も追加しています。@paramは型と引数の名前、説明を記述します。

/**
 * ほげを返します
 * @return {string}
 */
function getHoge() {
  return 'hoge';
}

上記は返却する値の説明を@returnを使って書いています。

JSDocのコメントでプログラムが読みやすくなる

プログラムを書く量は増えますし無くても動くが、可読性は間違いなくあがります。javascriptだけでなく他の言語でも同様の定義があるので使えるようにする。

参考サイト