JSDoc使い方メモ

More than 5 years have passed since last update.

JSDoc で API ドキュメントを生成する方法と、一部のドキュメンテーションタグの使い方についてメモする。


環境


OS

Windows7 64bit


Java

1.7.0_51


JSDoc

3.2.2


インストール


Java

Mozilla Rhino を使った方法でドキュメントを生成するので、 Java が必要。

インストール方法は割愛。


JSDoc 3

GitHub からダウンロードできる。

tags から v3.2.2 を選択して、 zip でダウンロードする。

zip を解凍したら、解凍後のフォルダにパスを通し、コマンドラインからヘルプを表示できることを確認する。

>jsdoc --help

OPTIONS:
-t, --template <value> The path to the template to use. Default: path/to/jsdoc/templates/default
-c, --configure <value> The path to the configuration file. Default: path/to/jsdoc/conf.json
-e, --encoding <value> Assume this encoding when reading all
(以下略)


ドキュメントを生成する


フォルダ構成

src

└─main
└─java
└─webapp
└─js
test.js


test.js

/**

* @classdesc This is MyClass.
* @constructor
*/

function MyClass() {
/**
* method
* @param hoge {Object} - hoge Object
*/

this.method = function() {
};
}

コマンドプロンプトでトップのフォルダに移動し、以下のコマンドを実行する。

>jsdoc -r src

すると、 out フォルダの下に API ドキュメントが HTML 形式で出力される。

>cd out

>tree /f
│ global.html
│ index.html
│ MyClass.html
│ test.js.html

├─scripts
│ │ linenumber.js
│ │
│ └─prettify
│ Apache-License-2.0.txt
│ lang-css.js
│ prettify.js

└─styles
jsdoc-default.css
prettify-jsdoc.css
prettify-tomorrow.css

ブラウザで開くと↓のような感じ。

jsdoc_sample.jpg


ドキュメンテーションタグの書き方


namepath について

@link タグなどでクラスのインスタンスメンバーやインナーメンバーを参照するときは、 namepath という記法を使う。

/**

* <ul>
* <li>{@link Hoge#instanceMethod}
* <li>{@link Hoge~innerFunction}
* <li>{@link Hoge.staticMethod}
* </ul>
* @constructor
*/

function Hoge() {
/**
* インスタンスメソッド
*/

this.instanceMethod = function() {};

/**
* インナー関数
*/

function innerFunction() {}
}

/**
* スタティックメソッド
*/

Hoge.staticMethod = function() {};

jsdoc_namepath.jpg

記法
指すモノ

ClassName#memberName
インスタンスメンバー

ClassName~memberName
インナーメンバー

ClassName.memberName
スタティックメンバー


@param : 関数の引数を宣言する


基本形

/**

* 関数
* @param {string} str - 文字列の引数
* @param {number} num - 数値の引数
* @param {Object} obj - オブジェクトの引数
* @param {MyClass} myClass - MyClass インスタンスの引数
*/

function func() {}

/**
* @constructor
*/

function MyClass() {}

jsdoc_param_1.jpg


引数が任意であることを宣言する

/**

* 関数
* @param {string} [str] - 文字列の引数
* @param {number} [num=300] - 数値の引数
*/

function func() {}

jsdoc_param_2.jpg

省略したときのデフォルト値も宣言できる。


@return : 戻り値を説明する

/**

* 関数
* @return {boolean} 真偽値を返す
*/

function func() {}

jsdoc_return.jpg


@throws : 関数がスローする例外について説明する

/**

* 関数
* @throws {string} エラーメッセージをスローする
*/

function func() {}

jsdoc_throws.jpg


@constructor : 関数をコンストラクタ関数として宣言する

/**

* ここの説明はコンストラクタの説明になる。
* @constructor
*/

function MyClass() {}

jsdoc_class.jpg


@classdesc : クラスの説明を記述する

/**

* コンストラクタの説明
* @constructor
* @classdesc クラスの説明
* @param {string} param - パラメータ
*/

function MyClass(param) {
}

jsdoc_classdesc.jpg


@extends : 親クラスを宣言する

/**

* 親クラス
* @constructor
*/

function ParentClass() {
}

/**
* 子クラス
* @constructor
* @extends ParentClass
*/

function ChildClass() {
}

ChildClass.prototype = new ParentClass();

jsdoc_augments.jpg

@augments タグでも同じように親クラスを明示できる。


@link : リンクを貼る

/**

* <ul>
* <li>{@link http://www.google.co.jp Google}
* <li>{@link MyClass#hoge}
* </ul>
* @constructor
*/

function MyClass() {

/**
* hoge 関数
* {@link MyClass}
*/

this.hoge = function() {};
}

jsdoc_link.jpg


@example : 実装例を提示する

/**

* 関数
* @example
* var result = plus(1, 3);
* // result = 4
*/

function plus(a, b) {
return a + b;
}

jsdoc_example.jpg


@deprecated : 非推奨を宣言する

/**

* 関数
* @deprecated 使ってはいけない
*/

function func() {}

jsdoc_deprecated.jpg


@type : 変数の型を明示的に宣言する

/**

* これはオブジェクトです。
* @type {object}
*/

var hoge = {};

/**
* これは数値です。
* @type {number}
*/

var fuga = 10;

/**
* これは {@link MyClass} のインスタンスです。
* @type {MyClass}
*/

var piyo = new MyClass();

/**
* @constructor
*/

function MyClass() {}

jsdoc_tyoe.jpg


@typedef : 独自の型を宣言する

/**

* Hoge 型です。
* @typedef {object} Hoge
*/

jsdoc_tyoedef.jpg


@prop : プロパティを宣言する

/**

* Hoge 型です。
* @typedef {object} Hoge
* @prop {string} str - 文字列のプロパティ
* @prop {number} num - 数値のプロパティ
*/

jsdoc_prop.jpg


@file : ファイルの説明を記述する


hoge.js

/**

* @file ほげファイル
*/



fuga.js

/**

* @file ふがファイル
*/


jsdoc_file.jpg


@callback : コールバック関数の定義を宣言する

/**

* @constructor
*/

function MyClass() {
/**
* メソッド
* @param {MyClass~MyCallback} callback - コールバック関数
*/

this.execute = function(callback) {
};
}

/**
* コールバック関数の説明
* @callback MyClass~MyCallback
* @param {number} hoge - 引数1
* @param {string} fuga - 引数2
*/

jsdoc_callback.jpg

ドキュメントコメントだけ書いて、 @callback タグをつけると、コールバック関数単独で型を定義できる。

上記例ではタグのパラメータに MyClass~MyCallback と指定しているので、 MyClass の内部メンバーとして型が定義されている。

他のクラスなどでも使用するようなコールバック関数の場合は以下のようにしてグローバルに宣言することもできる。

/**

* @constructor
*/

function MyClass() {
/**
* メソッド
* @param {MyCallback} callback - コールバック関数
*/

this.execute = function(callback) {
};
}

/**
* コールバック関数の説明
* @callback MyCallback
* @param {number} hoge - 引数1
* @param {string} fuga - 引数2
*/

jsdoc_callback_global.jpg


@event : イベントオブジェクトを宣言する

/**@constructor*/

function MyClass() {

/**
* イベントをキックする関数
* @fires MyClass~MyEvent
*/

this.kickEvent = function() {};

/**
* イベント実行キック時に渡されるオブジェクト
* @event MyClass~MyEvent
* @type {object}
* @property {string} name - イベント名
*/

}

jsdoc_event.jpg

@fire タグで、実行するイベントを宣言できる。


@namespace : 名前空間を宣言する


基本

/**

* @namespace
*/

var aaa = {
/**
* @constructor
*/

Hoge: function() {},

/**
* @namespace
*/

bbb: {
/**
* @constructor
*/

Fuga: function() {}
}
};

/**
* @namespace
*/

aaa.bbb.ccc = {
/**
* @constructor
*/

Piyo: function() {}
};

jsdoc_namespace_1.jpg

jsdoc_namespace_2.jpg

jsdoc_namespace_3.jpg


名前空間のオブジェクトを一旦別の変数に代入している場合

/**

* @namespace
*/

var aaa = {};

var alias = aaa;

/**
* @namespace
*/

alias.bbb = {};

jsdoc_namespace_4.jpg

jsdoc_namespace_5.jpg

そのままだと bbb は単独の名前空間として認識されてしまう。

aaa.bbb というふうにしたい場合は以下のようにする。

/**

* @namespace
*/

var aaa = {};

var alias = aaa;

/**
* @namespace bbb
* @memberof aaa
*/

alias.bbb = {};

jsdoc_namespace_6.jpg

jsdoc_namespace_7.jpg

@namespace で名前を明示して、 @memberof で所属している名前空間を明示する

(2階層以上ある場合は @memberof aaa.bbb のように . 区切りで所属する名前空間の完全名を指定する)。


参考