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

JavaScript開発を見直そう(前編)

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

遠藤 太志郎
株式会社インテック
ネットワーク&アウトソーシング事業本部

2009/6/9

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

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

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

●Animal.js
/** 
 * @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ファイルも増えていくので、このような一覧表を利用する機会も多くなっていくだろう。

画面1 File Index
File Index

■ファイルヘッダ

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

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

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

画面2 File IndexのAnimal.js部分
File IndexのAnimal.js部分

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

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

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

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

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

画面3 AnimalクラスのJavaScript Doc
AnimalクラスのJavaScript Doc

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

画面4 Class Index
Class Index

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

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

■フィールド変数

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

●Animal.jsのフィールド変数
    /**
     * 名前
     * @return {String}
     */
    this.name = name;
 
    /**
     * 性別
     * @return {String}
     */
    this.sex = sex;

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

画面5 フィールドの概要
フィールドの概要

■メソッド

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

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

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

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

画面6 メソッドの概要
メソッドの概要

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

画面7 メソッドの詳細
メソッドの詳細

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

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

prev
2/3
next

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

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


Coding Edge フォーラム 新着記事
@ITメールマガジン 新着情報やスタッフのコラムがメールで届きます(無料)

注目のテーマ

>

Coding Edge 記事ランキング

本日 月間