【Javascript】JSDocコメントの書き方、メリット

JavascriptでJSDocコメントを書く方法についてまとめました。

## JSDocコメントとは

JSDocコメントとは、次のような「関数」「変数」の宣言前に次のようなコメントを書く記法です。

/**
 * 例示のための関数です
 * @param  {Number} x1 数学の点数
 * @param  {Number} x2 英語の点数
 * @return {Number}  数学と英語の合計点
 */
function Mytest(x1, x2) {
    /**
    * ユーザー名を格納するための変数です
    * @type {String}
    */
    var userName = '';

    return x1 + x2;
    };
}

## JSDocコメントのメリット

JSDocコメントのルールにしたがってコメントを書くことで、次の利点が得られます。

JSDocの基本ルールは「Google JavaScript Style Guide 和訳」で解説されています。
そのポイントを下記にまとめました。

## プログラム全体の説明文

/**
 * このプログラムはテストです。
 * Ver.1.1
 */

## 「関数」「変数」の説明文

/**
 * 例示のための関数です
 * @param  {Number} x1 数学の点数
 * @param  {Number} x2 英語の点数
 * @return {Number}  数学と英語の合計点
 */
function Mytest(x1, x2) {
    /**
    * ユーザー名を格納するための変数です
    * @type {String}
    */
    var userName = '';

    return x1 + x2;
    };
}

## 「配列」「連想配列」の説明文

/**
 * 〇〇の配列です
 * @type {Array}
 */
var myArray = [];

/**
 * 〇〇の連想配列です
 * @type {Object}
 */
var myObject = {
  "id": 1
  "name": "my text"
}

## 「クラス」「プロパティ」「メソッド」の説明文

/**
 * 〇〇のクラス
 * @constructor
 */
var myClass = function() {
  /**
   * 〇〇のプロパティ
   * @type {Number}
   */
  this.src1 = 0;
  /**
   * 〇〇のプロパティ
   * @type {String}
   */
  this.src2 = "";
}

/**
 * 〇〇のクラスメソッド
 * @param {Number} src1 メソッドの引数の説明
 * @return {Number} メソッドの戻り値の説明
 */
myClass.prototype.myMethod(src1) {
  return 0;
}