【YUIDoc】JavaScriptのドキュメントを生成ツールを試してみた。

アジェンダ

• YUIDocとは?
• 動作環境について
• インストール
• YUIDocのコメント書き方
• 動作確認

YUIDocとは?

JavaScriptのドキュメントを生成ツールです。

公式サイト: YUIDoc - Javascript Documentation Tool

動作環境について

• OS:windows7
• node.js

インストール

Node.jsをインストールしている必要があります。
Node.jsのインストール方法については、弊社野中のこちらの記事をご参考にインストールしてみてください。

YUIDocをインストールする。

それではYUIDocパッケージを以下コマンドからインストールしてみます。

npm -g install yuidocjs.

イントール完了後、バージョンを確認してみます。ブログ執筆時はバージョン0.3.45でした。

yuidoc -v
0.3.45

YUIDocのコメント書き方

YUIDocのコメントの記述の仕方は大きくみっつあります。

クラス用のコメント記述方法

jsは厳密にはクラスをサポートしていませんが、クラスを模倣した機能を指すものかと思います。

/**
* This is the description for my class.(クラスの概要・説明を記述)
*
* @class MyClass (クラス名の記述)
* @constructor
*/

メソッド用のコメント記述方法

/**
* My method description.  Like other pieces of your comment blocks,
* this can span multiple lines.(メソッドの概要・説明を記述)
*
* @method methodName (メソッド名の記述)
* @param {String} foo Argument 1　(メソッド内で使用するパラメータの概要を記述します。)
* @param {Object} config A config object
* @param {String} config.name The name on the config object
* @param {Function} config.callback A callback function on the config object
* @param {Boolean} [extra=false] Do extra, optional work
* @return {Boolean} Returns true on success (return の概要・説明)
*/

プロパティ用のコメント記述方法

/**
* My property description.  Like other pieces of your comment blocks, 
* this can span multiple lines.(プロパティの概要・説明を記述)
* 
* @property propertyName　(プロパティ名の記述)
* @type {Object}(プロパティのタイプを記述)
* @default "foo"(デフォルト値の記述)
*/

動作確認

インストールができたので、今度は実際に動作確認してみたいと思います。
動作確認用に、以下のような作業ディレクトリを確認用のjsファイルを作成します。

～/yuidoc/assets/js/example.js

/**
* MyClassの説明
*
* @class MyClass
* @constructor
*/
function MyClass() {

    /**
    * hogeメソッドです。
    *
    * @method hoge
    * @param {String} name
    * @param {Int} age 
    */

    this.hoge = function(name , age){

        //処理を記述

    }

    /**
    * fugaプロパティです。
    * 
    * @property fuga
    * @type Int
    * @default 10
    */

    this.fuga  =  10;

}

ドキュメントを出力する。

コンソール画面に移動し、出力確認用example.jsファイルがあるところまで移動し、以下コマンドを入力します。
yuidocコマンドの後に、出力先を指定(今回は同階層を指定)、-oオプションをつけて実行しました。

#～/yuidoc/assets/js/
yuidoc ./ -o

同階層にoutフォルダが作成され、フォルダ内にドキュメントファイルが出力されます。

index.htmlを開くと以下の画面が確認できます。example.jsで記述したMyClassのメニューが確認できます。

メソッドコメントの確認

プロパティコメントの確認

YUIDocにてjavascriptのドキュメントを出力することができました。

まとめ

各種別のコメントにて、概要が確認できるようになりました。ひとつのプロジェクトで複数人で開発することは多々ありドキュメント化しておくことでメンバー間の認識の共有がスムーズにできるかと思います。

今回はコンソール画面がから直接コマンドを叩いて実行しましたが、次回YUIDocドキュメントの自動出力を試してみます。