JavaScript: JSDoc3を使い始めました

最終更新: 2018-07-27

規則に沿って記述されたコメントを元に、簡単にHTML形式のAPIドキュメントを作ってくれます。
以前はJava上でJSDocを動かしていましたが、今はnpmを頻繁に利用しているので、そちらからJSDocを利用しています。
Javaについては下記の記事が詳しいです。
https://qiita.com/opengl-8080/items/a36679f7926f4cac0a81

環境
Node.jsをインストールする
JSDocをインストールする
JSDocでAPIドキュメントを出力する
(余談) 便利なタグ@lends

環境

Windows10 64bit

Node.jsをインストールする

下記から最新版をダウンロードしてインストールします。
https://nodejs.org/

# PowerShell上で確認する
# バージョンが表示されれば成功
> node -v
v10.7.0

JSDocをインストールする

Node.jsのパッケージマネージャであるnpmを通じて入手します。

# グローバルで利用したいので、-g をつける
> npm i -g jsdoc

# 確認のため、バージョンを表示させる
> jsdoc -v
JSDoc 3.5.5 (Thu, 14 Sep 2017 02:51:54 GMT)

JSDocでAPIドキュメントを出力する

公式の解説に沿ってタグをつけたら、下記のコマンドで出力します。
コマンドラインでの利用方法も公式で解説されています。
http://usejsdoc.org/about-commandline.html

# フォルダ「./out」内に出力される
# オプション「-r」で、階層を潜ってJSファイルを探してくれる
> jsdoc -r [JSファイルが入っているフォルダ]

# フォルダ「./documentation」内に出力される
> jsdoc -r [JSフォルダ] -d ./documentation

# プライベートなメンバも文書に含める
> jsdoc -r [JSフォルダ] -p

(余談) 便利なタグ`@lends`

最近、私はクラスの継承を下記のように記述しています。

// jQueryを利用

// スーパークラス
function Class1(arg1, arg2) {
  this.prop1 = arg1 + arg2;
}
$.extend(Class1.prototype, {
  setProp1: function(arg) {
    this.prop1 = arg;
  },
  getProp1: function() {
    return this.prop1;
  },
});

// サブクラス
function Class2(arg1, arg2) {
  Class1.apply(this, arguments);
  this.setProp1(this.getProp1() + 10);
}
Class2.prototype = Object.create(Class1.prototype);
Class2.prototype.constructor = Class2;
$.extend(Class2.prototype, {
  meth2: function() {
    return this.getProp1() + 9;
  },
});

参照: JavaScriptの継承について

このとき、プロトタイプにメンバを追加している箇所をJSDocに理解してもらうためのタグが@lendsです。
オブジェクトリテラルの直前に記述することで、そのオブジェクトのメンバを、任意のクラスのメンバとして認識するそうです。

参照: Use JSDoc: @lends

実際にはこのように書きます。

// jQueryを利用

/**
 * プロパティ"Prop1"を初期化する
 * @constructor
 * @classdesc 親クラス
 */
function Class1(arg1, arg2) {
  this.prop1 = arg1 + arg2;
}

$.extend(Class1.prototype, /** @lends Class1.prototype */ {
  /**
   * セッター
   * @param {number} arg Prop1に代入する数値
   */
  setProp1: function(arg) {
    this.prop1 = arg;
  },
  /**
   * ゲッター
   * @return {number} Prop1の値
   */
  getProp1: function() {
    return this.prop1;
  },
});

/**
 * 親クラスのコンストラクタの実行後に、プロパティ"Prop1"を更に加工する。
 * @constructor
 * @augments Class1
 * @classdesc Class1を継承したクラス
 */
function Class2(arg1, arg2) {
  Class1.apply(this, arguments);
  this.setProp1(this.getProp1() + 10);
}

Class2.prototype = Object.create(Class1.prototype);

Class2.prototype.constructor = Class2;

$.extend(Class2.prototype, /** @lends Class2.prototype */ {
  /**
   * クラス2の独自のメソッド
   * @return {number} 独自に加算した値
   */
  meth2: function() {
    return this.getProp1() + 9;
  },
});