カテゴリー：JavaScript

JavaScriptのAPIドキュメント生成ツール YUIDocがいい感じ

こんにちわ。最近、英語ができないことにコンプレックスを持ち始めたkudoxです。以前、JavaScriptのAPIドキュメント生成にJSDoc Toolkitを使用したことがあるのですが、私の使い方が悪いのか、かなり手を焼いた記憶があります。そこで、CreateJSも使用しているYUIDocを使ってみました。これが、かなりいい感じだったので使い方をご紹介したいと思います。

YUIDocのインストール

YUIDocを使うには、Node.jsとパッケージ管理ツールnpmが必要になるようなので、インストールしましょう。私は、Macportsを使ってインストールしましたが、不安になるくらい簡単です。

Node.jsのインストール

まず、ターミナルで下記コマンドを実行してNode.jsをインストールします。

ターミナル

sudo port install nodejs

npmのインストール

続いて、ターミナルで下記コマンドを実行してnpmをインストールします。

ターミナル

sudo port install npm

YUIDocのインストール

最後は本丸のYUIDocのインストールです。ターミナルで下記コマンドを実行してYUIDocをインストールします。以上、簡単でしたね。

ターミナル

sudo npm -g install yuidocjs

コメントの書き方

YUIDocは、ASDocやJSDocと同様にJavaScriptのソースコードに所定の形式でコメントを入れておくことにより、ドキュメントを書き出してくれるようになります。YUIDocのコメントの書き方を見てみましょう。

名前空間

@namespace で名前空間を指定することができます。下記の例では、名前空間がcreatejsになります。

JavaScript

/**
* @namespace createjs
**/
this.createjs = this.createjs || {};

クラス

クラスを示すには、最初にクラスの説明文を入れ、次の行で @class に続けてクラス名を指定します。また、コンストラクタには @constructor を付けます。

JavaScript

/**
* クラスの説明文。
* @class BitmapData
* @constructor
**/
function BitmapData(image, width, height, fillColor) {
}

メソッド

メソッドを示すには、最初にメソッドの説明文を入れ、次の行で @method に続けてメソッド名を指定します。引数は @param で示し、省略可能な引数は[ ]で引数名を囲みます。戻り値は @return で示します。書式は下記の例をご覧下さい。

JavaScript

/**
* メソッドの説明文。
* @method メソッド名
* @param 引数名 {引数の型} 引数の説明文。
* @param [引数名=デフォルト値] {引数の型} 引数の説明文。
* @return {戻り値の型} 戻り値の説明文。
**/

プロパティ

プロパティを示すには、最初にプロパティの説明文を入れ、次の行で @property に続けてプロパティ名を指定します。@type でプロパティの型、@default でデフォルト値を指定することができます。

JavaScript

/**
* プロパティの説明文。
* @property プロパティ名
* @type プロパティの型
* @default デフォルト値
**/

staticメンバ

静的なプロパティやメソッドを示すには @static を付けます。@class に対して付けることもできます。

JavaScript

/**
* メソッドの説明文。
* @static
* @method メソッド名
**/

コードの記述例

コードの記述例を示すには @example に続けてコードの記述例を示します。記述例では、HTMLを使うこともできます。

JavaScript

/**
* メソッドの説明文。
* @method メソッド名
* @example
* <pre><code>コードの記述例</code></pre>
**/

その他のタグ

YUIDocには、ここで紹介した以外にも様々なタグが用意されています。お腹いっぱいにならなかった方は、英語のページになりますがこちらをご覧下さい。

yuidoc.jsonの作成

YUIDocでJavaScriptのAPIドキュメントを書き出すには、yuidoc.jsonという名前の設定ファイルが必要になります。下記は最もシンプルなyuidoc.jsonの記述例です。その他のオプションについては、英語のページになりますがこちらをご覧下さい。

yuidoc.json

{
    "name": "BitmapData for EaselJS",
    "description": "BitmapData for EaselJS API documentation.",
    "version": "0.8.5",
    "url": "https://kudox.jp/java-script/createjs-easeljs-bitmapdata",
    "options": {
        "outdir": "./docs",
        "paths":["./"]
    }
}

APIドキュメントの書き出し

以上で準備は完了です。実際にYUIDocでAPIドキュメントを書き出してみましょう。まず、対象となるJSファイルと先程作成したyuidoc.jsonを同じディレクトリに入れます。ここではデスクトップに作成したtestディレクトリに入れました。

jsファイルとyuidoc.jsonを入れたディレクトリ

次にターミナルのcdコマンドで先程作成したtestディレクトリに移動します。

ターミナル

cd Desktop/test

いよいよ佳境に入って参りました。後は、ターミナルでyuidocコマンドを実行するだけです。するとカレントディレクトリにdocsディレクトリが書き出されます。

ターミナル

yuidoc

docsディレクトリ内のindex.htmlをブラウザで開いてみましょう。デフォルトのテーマではこんな感じになります。

YUIDocのdefaultテーマのサンプル

YUIDocは、テーマを変更することで書き出されるドキュメントのデザインを変更することができます。現状、デフォルトで用意されているテーマは、defaultとsimpleの2つです。テーマを変更するには、-Tオプションで使用するテーマを指定します。

ターミナル

yuidoc -T simple

テーマをsimpleにして書き出すとこんな感じになります。どちらもすっきりしたデザインでいい感じですね。

YUIDocのsimpleテーマのサンプル

以上、YUIDocの使い方レポートでした。