トップ   編集 凍結 差分 バックアップ 添付 複製 名前変更 リロード   新規 一覧 単語検索 最終更新   ヘルプ   最終更新のRSS

JavaScript:YUIdocでコメントからAPIドキュメントを生成

Last-modified: 2014-03-09 (日) 17:35:22 (1380d)
Top / JavaScript:YUIdocでコメントからAPIドキュメントを生成

JavaScript?:YUIdocでコメントからAPIドキュメントを生成

YUIdocをつかって、JavaScript?のコメントからAPIドキュメントを生成します。

出力されるHTMLがすごいきれいでイケてますw

公式サイト

YUIdocのインストール

  1. nodejs,npmのインストール
    epelを設定していれば、yumでインストール可能です。
    こちらを参照
    https://github.com/joyent/node/wiki/Installing-Node.js-via-package-manager#wiki-rhelcentosscientific-linux-6
    epelの設定まで含めるとこんな感じです。
    yum repolist
    rpm -Uvh http://download-i2.fedoraproject.org/pub/epel/6/i386/epel-release-6-8.noarch.rpm
    sudo yum install nodejs --enablerepo=epel
    sudo yum install npm --enablerepo=epel
  2. yuidocjsのインストール
    npmでインストールします。
    sudo npm -g install yuidocjs

以上でインストール完了です。

インストールが完了すると、「yuidoc」というコマンドが実行可能となります。

YUIdocでAPIドキュメントを生成

YUIdocでAPIドキュメントを生成するためには、以下の2つを作成する必要があります。

  • yuidoc.json
  • コメントの入ったソースコード

これだけで、YUIdocがイカしたHTMLのAPIドキュメントを生成してくれます。

1.yuidoc.json

こんな感じで書きます。

{
    "name": "Test YuiDoc",
    "description": "YUIdocのテスト.",
    "version": "0.1",
    "url": "http://www.hiihah.info",
    "options": {
        "outdir": "../../docs",
        "paths":["./"],
        "exclude":"resources"
    }
}

まあ、見たままですねw。

特に重要なパラメータとしては以下の3つがあります。

  • outdir : html一式の出力先。これを誤ると、変なところに一式が出力されて、掃除が大変なので気をつけましょうw(当方、一回喰らいましたw)
  • paths : APIドキュメント生成対象のコードが格納されているルートディレクトリ
  • exclude : 除外対象パターン。pathsからの相対パスにたいしてパターンマッチ可能
    この場合は、「resources」と言う文字列が含まれるものについては除外する設定となっています。

詳細は以下のURLを参照ください。※ページ中程にyuidoc.jsonに関する記述があります。

2.コメント入りのJavaScript?コード

コメントの仕様は以下のURLに記載されています。

サンプルは以下の通りです。

/**
YUIdoc出力サンプルのモジュール

@module sampleModule
**/
this.createjs = this.createjs || {};

/**
YUIdoc出力サンプルのクラス
@class Sample
@constructor
@param args1 {number} サンプルの引数1
@param args2 {String} サンプルの引数2
**/
function Sample(args1, args2) {
	var a,b,sampleProperty,add;
	a = args1;
	b = args2;

	/**
	* サンプルのプロパティ
	* @property sampleProperty
	* @type number
	* @default 0
	**/
	sampleProperty = 0;

	/**
	* 引数を足し算するメソッド
	* @method add
	* @param a {number} 足し算をする数値
	* @param b {number} 足し算をする数値
	* @return {number} a+bを返却
	**/
	add = function(a,b){
		return a + b;
	};
	
	return {
		c:c,
		add:add
	};
}

3.yuidocコマンドで出力

yuidoc.jsonをソースコードよりも上位のディレクトリに入れて、yuidoc.jsonが格納されているディレクトリでyuidocコマンドを実行すると、outdirに指定したディレクトリにAPIドキュメント一式が生成されます。

yuidoc

生成されたドキュメント

こんな感じです。

  • クラスの定義
    yuidoc_sample1.png
  • メソッドの定義
    yuidoc_sample2.png
  • プロパティの定義
    yuidoc_sample3.png

添付ファイル: fileyuidoc_sample3.png 677件 [詳細] fileyuidoc_sample2.png 748件 [詳細] fileyuidoc_sample1.png 811件 [詳細]