JsDoc Toolkitを使う!
コマンドラインオプション
最終更新:
aias-jsdoctoolkit
コマンドラインオプション
このページでは、コマンドラインからJsDoc Toolkitを実行しドキュメントを作成する方法について説明します。
- 公式サイトのhttp://code.google.com/p/jsdoc-toolkit/wiki/CommandlineOptionsを元に作成しました。
目次
サンプルの動作環境について
このページに記載されているサンプルは、以下の動作環境を想定しています。
- OS:Windows (コマンドプロンプト)
- JRE:JRE 6 ※「%JREインストールディレクトリ%¥bin」にpathが設定済みとする
- カレントディレクトリ:JsDoc Toolkitのインストールディレクトリ
記述例
java -jar jsrun.jar app\run.js c:\example\js\ -t=templates\jsdoc -d=c:\out\example -a
JsDoc ToolkitはJavaで実装されたJavaScript実行環境である"Rhino"上で動作します。RhinoはJsDoc Toolkitの配布パッケージに含まれており、実行アプリケーション"jsrun"から起動されます。そしてjsrunはJsDoc Toolkitのメインスクリプトである"run.js"へのパスをパラメータにとります。
したがってコマンドは必ず下のように開始されなければなりません。
java -jar jsrun.jar app\run.js ...
入力ファイルの指定
オプションを除くコマンドライン引数は、入力ファイルまたはディレクトリへのパスの指定と解釈されます。ディレクトリを指定した場合、配下のファイル全てが入力対象となります。(ただし条件があります。 -r オプションと -x オプションを参照してください。) 入力ファイルとディレクトリは複数指定でき、ファイルとディレクトリを混在させることも可能です。
java -jar jsrun.jar app\run.js one\file.js two\file.js -t=templates\jsdoc
java -jar jsrun.jar app\run.js myscripts\ -t=templates\jsdoc
java -jar jsrun.jar app\run.js myscripts\ one\file.js -t=templates\jsdoc
オプション
全てのオプションは -x または -x=value という形式で指定されます。(=の両側にスペースを入れないでください。)またオプションの出現順は特に意味を持ちません。
オプション名 | 説明 |
---|---|
-a --allfunctions |
ドックコメントが付いていない関数(メソッド)も出力します。このオプションを指定しない場合、ドックコメントが付いている要素だけが出力対象となります。 - 詳細はこちらを参照してください。 |
-c --conf |
オプション設定を含むコンフィグファイルのパスを指定します。 - コンフィグファイルの書き方はこちらを参照してください。 |
-d=<PATH> --directory=<PATH> |
出力ディレクトリを指定します。省略した場合、JsDoc Toolkitのインストールディレクトリ直下の"out"ディレクトリに出力されます。 - 詳細はこちらを参照してください。 |
-D="myVar:My value" --define="myVar:My value" |
ドキュメントの中で使用できるパラメータを独自に定義します。テンプレートを自作した場合などに使われます。このオプションは複数指定が可能です。 |
-e=<ENCODING> --encoding=<ENCODING> |
入力および出力ファイルの文字エンコーディングを指定します。 |
-E="REGEX" --exclude="REGEX" |
指定された正規表現にマッチするファイルを処理対象から除外します。このオプションは複数指定が可能です。 |
-h --help |
ヘルプメッセージを表示し、終了します。 |
-m --multiples |
このオプションを指定すると、シンボルが重複して記述されている場合でも警告を出力しません。記述は最初に見つかったものが優先されます。 (2.4.0~) |
-n --nocode |
コードを全て無視し、@nameタグと共に記述された内容だけでドキュメントを作成します。 |
-o=<PATH> --out=<PATH> |
ログの出力先ファイルを指定します。(デフォルトでは、ログは標準出力に出力されます。) |
-p --private |
privateなスコープの要素(@privateタグか@innerタグがつけられた、あるいはアンダースコア( _ )から始まる名前を持つ)をドキュメントに出力します。 |
-q --quiet |
このオプションを指定すると、警告も含め処理中のメッセージを全て出力しません。 |
-r[=<DEPTH>] --recurse[=<DEPTH>] |
ソースディレクトリを何階層まで下にたどるかを指定します。 - 詳細はこちらを参照してください。 |
-s --suppress |
このオプションを指定すると、ソースコードを出力しません。 |
-S --securemodules |
ソースコードをSecurableModulesパターンで記述されたものとしてパースします。 (2.2.0~) |
-t=<PATH> --template=<PATH> |
出力フォーマットを定義するテンプレートを指定します。このオプションは必須です。 - 詳細はこちらを参照してください。 |
-T --test |
全てのユニットテストを実行し、終了します。 |
-u --unique |
標準テンプレートjsdocで、各クラスの詳細ページが必ずユニークになるようにファイルを作成します。大文字小文字を区別しないファイルシステムにおいて、クラス名に大文字小文字しか違いのないクラスの詳細ページファイル名が重複しないようにするためのオプションです。 (2.3.0~) |
-v --verbose |
処理内容について詳細なメッセージを出力します。 |
-x=<EXT>[,EXT]... -ext=<EXT>[,EXT]... |
読み込みの対象とするファイル拡張子を指定します。(デフォルトでは
js
のみです。) - 詳細はこちらを参照してください。 |
-Z | ソースコードから生成された全ての Symbol オブジェクトの内容をコンソールにダンプします。 |
テンプレートを指定する
出力ファイルを生成するには、ドキュメントのフォーマットを規定するテンプレートの指定が必須です。使いたいテンプレートを指定するには -t オプションを使用します。
java -jar jsrun.jar app\run.js myscripts\ -t=templates\jsdoc
注意: -t オプションにはファイル名ではなくディレクトリを指定しなければならず、かつそのディレクトリには"publish.js"という名前のファイルが存在しなければなりません。
- テンプレートの仕様、作成方法についてはこちらを参照してください。
出力ディレクトリを指定する
デフォルトでは作成されたドキュメントはJsDoc Toolkitがインストールされているディレクトリ直下の"out"ディレクトリに出力されます。出力ディレクトリを変更するには、 -d オプションを使用します。
java -jar jsrun.jar app\run.js myscripts\ -t=templates\jsdoc -d=my_docs myscripts\
ディレクトリを再帰的にたどる
入力パスとしてディレクトリを指定した際、デフォルトの動作ではJsDoc Toolkitはディレクトリ直下にある拡張子が".js"の全ファイルを入力ファイルとしますが、サブディレクトリをそれ以上たどることはありません。
JsDoc Toolkitに対しサブディレクトリを更に下へ進ませたい場合は、
-r
オプションを使用します。このオプションはデフォルトでは10階層までのサブディレクトリを走査し入力ファイルを収集しますが、下のように階層数を明示指定することもできます。
java -jar jsrun.jar app\run.js -r=4 myscripts\ -t=templates\jsdoc
ソースファイルの拡張子をカスタマイズする
デフォルトではJsDoc Toolkitはファイル拡張子が".js"(大文字小文字は区別しません)のファイルだけを入力ファイルとして読み込みます。異なる拡張子を指定したい場合は、 -x オプションを使用します。例えば拡張子".sc"のファイルの場合は、以下のようにします。
java -jar jsrun.jar app\run.js -x=sc myscripts\ -t=templates\jsdoc
下のように複数の拡張子を指定することもできます。
java -jar jsrun.jar app\run.js -x=sc,js,txt myscripts\ -t=templates\jsdoc
注意:
-x
オプションの値にはドット(.)をつけないでください。例えば
-x=.sc
は正常に動作しません。
ドックコメントの書かれていない関数を出力する
デフォルトでは、ドキュメントに出力されるのはドックコメントが書かれている要素だけです。コメントされていない関数(メソッド)もドキュメントに含めるには、 -a オプションを指定します。
java -jar jsrun.jar app\run.js -t=templates\jsdoc -a myscripts\
注意: -a オプションを使用しても、ドックコメントが付いていない変数(プロパティ)は出力されません。
コンフィグファイルを使う
同じコマンドを何度も入力するのが面倒になってきたら、 -c オプションでコンフィグファイルを使用することもできます。
java -jar jsrun.jar app\run.js -c=sample.conf
コンフィグファイルの内容は、下に示すようなJSONに良く似た形式のテキストデータです。全体が1つの"オブジェクト"となっており、各オプションが"プロパティ"に相当します。
- サンプルのコンフィグファイルが「conf¥sample.conf」という名前でJsDoc Toolkitの配布パッケージに同梱されています。
{
// source files to use
_: ["myscripts\\", "one\\file.js"],
// document all functions, even uncommented ones
a: true,
// including those marked @private
p: true,
// some extra variables I want to include
D: {generatedBy: "Michael Mathews", copyright: "2008"},
// use this directory as the output directory
d: "docs",
// use this template
t: "templates\\jsdoc"
}
上のコンフィグファイルは、コマンドラインで下のように記述したのと同じ意味です。
java -jar jsrun.jar app\run.js myscripts\ one\file.js -a -p -D="generatedBy:Michael Mathews" -D="copyright:2008" -d=docs -t=templates\jsdoc
コンフィグファイルのポイントをまとめると以下のようになります。
- プロパティ"_"には入力ファイルパスを配列で指定します。ファイルが1つであっても配列で指定してください。
- -D オプションは1つのオブジェクトとし、名前と値のセットを記述します。
- Windows環境の場合、パス区切り文字(¥)をエスケープしてください。
- コンフィグファイル内の指定とコマンドライン上のオプション指定が重複した場合、コマンドラインの方が優先されます。
サンプルシェルスクリプト
バージョン2.2.0以降のJsDoc Toolkitには、サンプルシェルスクリプト jsrun.sh が同梱されています。参考にしてみてください。
関連項目
- JsDoc Toolkit Ant Taskは、JsDoc ToolkitをAntタスクとして実行できるようにするラッパープログラムです。