JsDoc Toolkitによる開発効率向上を
目指して

一般的なクラスのJavaScript Docの作り方

　この項では、一般的なインスタンスタイプのクラスにおけるJavaScript Docの作成方法について解説する。

　一般的なインスタンスタイプのクラスとは、以下のようなクラスである。なお、この動物エンティティクラスは、山田祥寛氏の連載「Ajax時代のJavaScriptプログラミング再入門」の第4回「JavaScriptでオブジェクト指向プログラミング」を参考にさせていただいた。

/** 
 * @fileOverview 動物クラスを記述するファイルです。
 * 
 * @author 遠藤 太志郎
 * @version 1.0.0
 */
 
/**
 * 動物の名前と性別をセットします。
 * 
 * @class 動物エンティティのクラスです。<br>
 * 動物の名前と性別の情報を所持し、それらを取り扱う機能を保有します。
 * 
 * @param {String} name	動物名
 * @param {String} sex	性別
 */
var Animal = function(name, sex) {
 
    /**
     * 名前
     * @return {String}
     */
    this.name = name;
 
    /**
     * 性別
     * @return {String}
     */
    this.sex = sex;
 
    /**
     * 文章化する。<br>
     * 名前と性別の情報を合わせて文章化する。
     * 
     * @param {String} sep 分割表示用マーク
     * @return {String} 表示用文章
     * 
     * @example 
     * tiger.toString("：");
     * 出力：「虎太郎：オス」
     * 
     */
    this.toString = function(sep) {
        return this.name + sep + this.sex;
    };
}

　JavaScriptはソースコードをJSファイルという形式で保存できる。また、JsDoc ToolkitはJSファイルをJavaScript Docに出力するツールである。従って、HTMLに直接に記述されたJavaScriptを変換することはできない。

　画面1がJavaScript Docである。このページはJSファイルの一覧を表示するメニューであるFile Indexだ。開発規模が大きくなるにつれてJSファイルも増えていくので、このような一覧表を利用する機会も多くなっていくだろう。

■ファイルヘッダ

　最初にファイルヘッダの説明をする。

/** 
 * @fileOverview 動物クラスを記述するファイルです。
 * 
 * @author 遠藤 太志郎
 * @version 1.0.0
 */

　JSファイル自体の説明を記すためのタグが@fileOverviewである。ファイルの作成者を示す@authorや、ファイルのバージョンを示す@versionなども、必要に応じて記述できる。

　このように、JavaScript Docソースの基本は@タグ＋説明文章である。このあたりはJava Docと何ら変わりはない。また同様に、1つのファイルには1つのクラスを記述し、そのファイル名とクラス名を同期させておくことをお勧めする。

■クラスとコンストラクタ

　クラスおよびコンストラクタについては、@classタグを使用し、下記のように記述することで出力が可能となる。

/**
 * 動物の名前と性別をセットします。
 * 
 * @class 動物エンティティのクラスです。<br>
 * 動物の名前と性別の情報を所持し、それらを取り扱う機能を保有します。
 * 
 * @param {String} name	動物名
 * @param {String} sex	性別
 */

　画面3を見れば分かるように、@classの前に書かれている部分がコンストラクタの説明と認識され、コンストラクタの概要部分に出力される。

　そして、@class以降がクラスの説明として認識され、ページのヘッダ部分に出力され、さらにClass Index（画面4）にも表示される。Class Indexとは、JavaScriptのクラスの一覧を表示するメニューである。

　このように、クラスの説明文を書いておくことで、一覧から目的のクラスを探すことができ、そのクラスのページを開けば具体的な説明も閲覧できるようになる。このあたりはJava Docでいうところのパッケージの選択後に表示されている状態に近いものがある。

　なお、Java Docにはパッケージごとに分別して出力する機能があるが、JavaScript Docにはパッケージの概念はない。もしパッケージごとに分別して管理したい場合は、パッケージごとにJavaScript Docを出力することになる。

■フィールド変数

　クラスが保有するフィールド変数は下記のように記述する。

    /**
     * 名前
     * @return {String}
     */
    this.name = name;
 
    /**
     * 性別
     * @return {String}
     */
    this.sex = sex;

　@return {String}とあるように、返り値に返却される型を表示できる。画面5でもフィールドの変数名と説明と共に、返り値の型が表示される。

■メソッド

　メソッドの説明は下記のように記述する。

    /**
     * 文章化する。<br>
     * 名前と性別の情報を合わせて文章化する。
     * 
     * @param {String} sep 分割表示用マーク
     * @return {String} 表示用文章
     * 
     * @example 
     * tiger.toString("：");
     * 出力：「虎太郎：オス」
     * 
     */
    this.toString = function(sep) {
        return this.name + sep + this.sex;
    };

　サンプルでは、クラスのフィールド変数として保有している「名前」と「性別」の情報を、引数で設定した分割表示用マークを間に入れて文章化するものである。

　画面への出力結果は以下のようになる。メソッドの概要（画面6）には、メソッドの機能説明と返り値の型が表示される。

　メソッドの詳細（画面7）にはパラメータの値のほか、@exampleタグを使用することにより、実際に使用する際の使用例を表示できる。

　以上で、一般的なクラスのJavaScript Docの作り方の解説は終了である。すでにJavaScript Docの記述方法の要領は理解していただけたのではないだろうか。要領はJava Docとほとんど同じである。タグの意味や記述する場所さえ分かっていれば、誰にでも簡単に記述することができるだろう。

　以降は、この項では説明できなかった残りの記述方法について述べる。ただし、@fileOverviewでファイルの説明が記述できたり、@returnタグで返り値が指定できたりするなど、重複する部分も非常に多いので、そういった部分は割愛する。

2/3

Index
JsDoc Toolkitによる開発効率向上を目指して
	Page1 Ajaxの登場と開発者の苦難 JavaScriptによる開発効率を上げられるか JsDoc Toolkitとは何か
	Page2 一般的なクラスのJavaScript Docの作り方
	Page3 StaticタイプのJavaScript Docの作り方 組み込みクラスのJavaScript Docの作り方 グローバルタイプのJavaScript Docの作り方 JavaScript docタグ

Coding Edgeフォーラム トップページ