JsDoc Toolkitを使う！
組み込みオブジェクト リファレンス
最終更新：
aias-jsdoctoolkit
-
view
組み込みオブジェクト リファレンス
このページではテンプレートで使用できるJsDoc Toolkitの組み込みオブジェクトとそのメンバの一部を説明します。
- JsDoc Tookitのソースコードから直接作成した、より詳細なドキュメントはこちらをご覧下さい。
目次
JSDOC 名前空間
JsDoc Toolkitが提供する各クラスのコンテナとして機能する名前空間です。クラスコンストラクタのほか、以下のプロパティが定義されています。特に opt プロパティはテンプレート作成者にとって重要です。
| プロパティ | 説明 |
|---|---|
|
<Object> JSDOC.opt |
optプロパティは無名オブジェクトで、プロパティとしてコマンドラインオプションの設定値を持っています。プロパティ名はコンフィグファイルで使用されている名称と同じです。 ユーザが設定した入力ファイルパスの配列は"_"プロパティにセットされています。またJsDoc Toolkitがそれをパースした実際のソースファイルのリストは、srcFilesプロパティに格納されています。 |
|
<String> JSDOC.VERSION |
JsDoc Toolkitのバージョン |
JSDOC.JsPlate クラス
JsPlateクラスはテンプレートファイルにシンボルオブジェクトなどのデータを適用し、整形されたドキュメントを生成します。
| コンストラクタ | 説明 |
|---|---|
| new JsPlate(templateFile) | 引数にテンプレートファイルのパスを取り、JsPlateオブジェクトを作成します。 |
| メソッド | 説明 |
|---|---|
|
<String> object.process(data[,compact]) |
テンプレートにデータを渡し、生成されたドキュメント文字列を返します。compact=trueとすると、テンプレートから改行と空白を削除して出力します。 |
JSDOC.SymbolSet クラス
SymbolSetはSymbolオブジェクトのコレクションクラスです。通常JsDoc Toolkitによって1つだけインスタンスが作成され、publish.js内の publish 関数は引数としてこのインスタンスを受け取ります。
| メソッド | 説明 |
|---|---|
|
<JSDOC.Symbol> object.addSymbol(symbol) |
Symbolオブジェクトを追加します。追加しようとしているシンボルと同じネームパスを持つシンボルが既に登録されている場合、ネームパスと関連付けられたオブジェクト内の参照は新たに追加されたSymbolオブジェクトに移ります。 |
|
<void> object.deleteSymbol(alias) |
シンボルのネームパスを引数として受け取り、対応するSymbolオブジェクトの登録を削除します。 |
|
<Symbol> object.getSymbol(alias) |
シンボルのネームパスを引数として受け取り、対応するSymbolオブジェクトを返します。ネームパスに対応するシンボルが存在しない場合の戻り値はundefinedです。 |
|
<Symbol> object.getSymbolByName(name) |
シンボルの名前（nameプロパティ）を引数として受け取り、対応するSymbolオブジェクトの内最初に見つかったものを返します。ネームパスに対応するシンボルが存在しない場合の戻り値はundefinedです。 |
|
<Boolean> object.hasSymbol(alias) |
シンボルのネームパスを引数として受け取り、対応するシンボルが存在すればtrueを、しなければfalseを返します。 |
|
<String[]> object.keys() |
オブジェクトに登録されている全てのSymbolオブジェクトのネームパスの配列を返します。 |
|
<String> object.renameSymbol(oldAlias,newAlias) |
oldAlias で登録されたシンボルのネームパスを newAlias に置換し、新しいネームパスを返します。このメソッドがSymbolオブジェクトのaliasプロパティそのものを書き換えてしまう点に注意してください。 |
|
<Symbol[]> object.toArray() |
オブジェクトに保持されている全てのSymbolオブジェクトの配列を返します。 |
JSDOC.Symbol クラス
Symbolクラスは１つのシンボルを表します。通常このクラスのインスタンスはSymbolSetオブジェクトのメソッドから取得されます。
| プロパティ | 説明 |
|---|---|
|
<String> object.alias |
このシンボルの完全なネームパス。ただしファイルシンボルの場合はファイルパスが設定されます。 |
|
<JSDOC.DocTag> object.augments |
@augmentsタグから作成された、このシンボルの継承元クラス情報を保持するDocTagオブジェクトの配列 |
|
<String> object.author |
作者情報。@authorタグが複数記述されていた場合、カンマ区切りの文字列に結合されています。 |
|
<String> object.classDesc |
クラスの説明文。@classタグまたは@namespaceタグの説明文が設定されています。 |
|
<JSDOC.DocComment> object.comment |
このシンボルのドックコメントをパースしたDocCommentオブジェクト |
|
<String> object.defaultValue |
デフォルト値。@defaultタグの内容が設定されています。 |
|
<String> object.deprecated |
非推奨情報。@deprecatedタグが複数記述されていた場合、改行文字区切りの文字列に結合されています。 |
|
<String> object.desc |
シンボルの説明文。ドックコメントの先頭に書かれたタグなしの説明文や、@descriptionタグの説明文が設定されています。またシンボル種別が
FILE
の場合、@fileOverviewタグの説明文が設定されています。 これらが複数記述されていた場合、改行文字区切りの文字列に結合されています。 |
|
<JSDOC.DocTag[]> object.example |
サンプルコード。@exampleタグをパースしたDocTagオブジェクトの配列です。 |
|
<JSDOC.DocTag[]> object.exceptions |
例外。@throwsタグをパースしたDocTagオブジェクトの配列です。 |
|
<Object[]> object.inherits |
@borrowsタグから作成された、メンバの借用関係を示す無名オブジェクトの配列。無名オブジェクトは以下のプロパティを持ちます。 alias -- 借用元メンバのネームパス as -- 借用先メンバのネームパス |
|
<JSDOC.Symbol[]> object.inheritsFrom |
@augmentsタグから作成された、このシンボルの継承元クラスを表すシンボルオブジェクトの配列 |
|
<String> object.isa |
シンボルの種別を表す文字列 CONSTRUCTOR -- クラス（コンストラクタ）、名前空間 FILE -- ファイル。@fileOverviewタグの内容を持ちます。 FUNCTION -- 関数、メソッド、イベント OBJECT -- 上記以外のオブジェクト（変数、プロパティなど） |
|
<Boolean> object.isConstant |
このシンボルが定数ならtrue |
|
<Boolean> object.isEvent |
このシンボルがイベントならtrue |
|
<Boolean> object.isInner |
このシンボルが内部関数ならtrue |
|
<Boolean> object.isNamespace |
このシンボルが名前空間ならtrue |
|
<Boolean> object.isPrivate |
このシンボルのスコープがprivateならtrue |
|
<Boolean> object.isStatic |
このシンボルが静的メンバならtrue |
|
<String> object.memberOf |
このシンボルがメンバとして定義されているシンボルのネームパス |
|
<JSDOC.Symbol[]> object.methods |
このシンボルがメンバとしているメソッドシンボルの配列。他のクラスから継承しているものも含みます。 |
|
<String> object.name |
このシンボルの名前。 alias がネームパスによるシンボルのユニークな識別子であるのに対し、nameプロパティにはメソッド名のような単純な名称が設定されます。 |
|
<JSDOC.DocTag[]> object.params |
シンボルのパラメータを表すDocTagオブジェクトの配列 |
|
<JSDOC.Symbol[]> object.properties |
このシンボルがメンバとしているプロパティシンボルの配列。他のクラスから継承しているものも含みます。 |
|
<String[]> object.requires |
このシンボルが依存するシンボルのネームパスの配列 |
|
<JSDOC.DocTag[]> object.returns |
メソッドの戻り値。@returnsタグをパースしたDocTagオブジェクトの配列です。 |
|
<String[]> object.see |
関連項目へのリンクを含むHTMLテキストまたはシンボルのネームパスの配列 |
|
<String[]> object.since |
このシンボルが使用可能になったバージョンに関する情報。@sinceタグが複数記述されていた場合、カンマ区切りの文字列に結合されています。 |
|
<String> object.srcFile |
このシンボルのソースファイルのパス |
|
<String> object.type |
データ型（クラスの場合はネームパス） |
|
<String> object.version |
バージョン。@versionタグが複数記述されていた場合、カンマ区切りの文字列に結合されています。 |
| メソッド | 説明 |
|---|---|
|
<JSDOC.Symbol> object.clone() |
このシンボルの複製を返します。 |
|
<Boolean> object.is(what) |
引数で指定したシンボル種別文字列が isa プロパティと一致していればtrueを返します。 |
|
<Boolean> object.isBuiltin() |
このシンボルがJavaScriptの組み込みの関数やオブジェクトを表していればtrueを返します。 |
|
<JSDOC.Symbol[]> object.getEvents() |
このシンボルに含まれる全てのイベントシンボルの配列を返します。 |
|
<JSDOC.Symbol[]> object.getMethods() |
このシンボルに含まれる全てのメソッドシンボルの配列を返します。 |
|
<Boolean> object.hasMember(name) |
引数で指定された名前かネームパスのシンボルをメンバを持っていればtrueを返します。 |
|
<Boolean> object.hasMethod(name) |
引数で指定された名前かネームパスのメソッドを持っていればtrueを返します。 |
|
<Boolean> object.hasProperty(name) |
引数で指定された名前かネームパスのプロパティを持っていればtrueを返します。 |
JSDOC.DocComment クラス
DocCommentオブジェクトはシンボルと関連付けられたドックコメントをパースした結果を保持します。シンボルオブジェクトの comment プロパティから取得できます。
| プロパティ | 説明 |
|---|---|
|
<String> object.src |
ドックコメントのソーステキスト |
|
<DocTag[]> object.tags |
ドックコメントに含まれるタグオブジェクトの配列 |
| メソッド | 説明 |
|---|---|
|
<JSDOC.DocTag[]> object.getTag(title) |
タグタイトル（タグ名から"@"を除いた文字列）を受け取り、このドックコメント内で該当するタグを表すDocTagオブジェクトの配列を返します。 |
JSDOC.DocTag クラス
DocTagオブジェクトはドックコメント内のタグをパースした結果をプロパティに保持しています。以下のプロパティに実際に値が設定されているかどうかは、タグの種類に依存します。
| プロパティ | 説明 |
|---|---|
|
<String> object.title |
タグタイトル（タグ名から"@"を除いた文字列） |
|
<String> object.desc |
説明文 |
|
<String> object.type |
データ型。@propertyタグなどデータ型定義が記述されているタグで値が設定されます。 |
|
<String> object.name |
データの名前。@paramタグなどデータ名定義が記述されているタグで値が設定されます。 |
|
<String> object.isOptional |
@paramタグにおいて、パラメータが省略可能ならtrueが設定されます。 |
|
<String> object.defaultValue |
@paramタグにおいて、パラメータのデフォルト値が設定されます。 |
| メソッド | 説明 |
|---|---|
|
<String> object.toString() |
オブジェクトの文字列表現として、 desc プロパティの値を返します。 |
JSDOC.PluginManager 名前空間
JSDOC.PluginManagerはプラグインの登録とイベントの発生を管理します。プラグインについての詳細はこちらを参照してください。
| メソッド | 説明 |
|---|---|
|
<void> JSDOC.PluginManager.registerPlugin(name,functionMap) |
プラグインをシステムに登録します。引数 name には登録される全プラグインの中で重複しない登録名を、 functionMap には各イベントへのハンドラ関数をプロパティに持つオブジェクトを指定します。 |
|
<void> JSDOC.PluginManager.run(eventName,handlerArg) |
引数 eventName で指定したイベントを発生させます。実行されるハンドラ関数には引数として handlerArg で指定したデータが渡されます。 |
SYS 名前空間
SYS名前空間は様々なシステム情報をプロパティに持ちます。特に pwd プロパティはテンプレート作成者にとって重要です。
| プロパティ | 説明 |
|---|---|
|
<String> SYS.os |
OS情報。アーキテクチャ、名称、バージョンをカンマ区切りで結合した文字列です。 |
|
<String> SYS.slash |
パス区切り文字 |
|
<String> SYS.userDir |
現在の作業ディレクトリ |
|
<String> SYS.javaHome |
Javaのホームディレクトリ |
|
<String> SYS.pwd |
app/run.jsの絶対パス |
IO 名前空間
IO名前空間はファイルの読み書きを実行するメソッドのコレクションです。
| メソッド | 説明 |
|---|---|
|
<void> IO.copyFile(inFile,outDir[,outFileName]) |
ファイルをコピーします。引数 outFileName を省略した場合はコピー元のファイル名がそのまま使われます。 |
|
<Boolean> IO.exists(path) |
指定されたパスが存在すればtrueを返します。 |
|
<void> IO.include(relativePath) |
SYS.pwd からの相対パスで指定されたファイルをロードします。 |
|
<void> IO.includeDir(relativePath) |
SYS.pwd からの相対パスで指定されたディレクトリに含まれるスクリプトファイル（拡張子が.jsのファイル）を全てロードします。 |
|
<String[]> IO.ls(dir[,recurse]) |
指定されたディレクトリの配下を再帰的に検索し、ファイルパスのリストを返します。引数 recurse は検索する階層数を表し、デフォルトは1です。 |
|
<void> IO.makeDir(path) |
ディレクトリを作成します。 |
|
<void> IO.mkPath(path) |
パス階層を作成します。 |
|
<String> IO.readFile(path) |
ファイルを読み込み、内容を文字列として返します。 |
|
<void> IO.saveFile(outDir,fileName,content) |
content で指定した文字列をファイルに保存します。 |
|
<void> IO.setEncoding(encoding) |
ファイルの文字コーディングを設定します。デフォルトは"utf-8"です。 |
LOG 名前空間
LOG名前空間はログメッセージの出力に関する機能を提供します。
| メソッド | 説明 |
|---|---|
|
<void> LOG.warn(msg[,e]) |
警告メッセージを出力します。eに例外オブジェクトを指定すると、ファイル名と行数が出力されます。 |
|
<void> LOG.inform(msg) |
情報メッセージを出力します。（-vコマンドラインオプションが指定されている場合のみ有効） |
Dumper名前空間
オブジェクト、配列などのデータの内容をダンプする機能を提供します。この名前空間をテンプレートから使用する場合、テンプレート自身で以下のようにjsファイルをロードしておく必要があります。
IO.include("frame/Dumper.js");
| メソッド | 説明 |
|---|---|
|
<String> Dumper.dump(data) |
指定されたデータを展開し、内容を文字列化して返します。 |
Link クラス
LinkクラスはシンボルやファイルへのHTMLリンク（<a>タグ）を作成する機能を提供します。Linkオブジェクトのメソッドのほとんどは自分自身への参照を返すため、以下のようにリンクの設定処理をチェーンした後、最終的に toString メソッドでタグ文字列を出力するのが標準的な使用方法です。
new Link().toSymbol("MySymbol").withText("マイシンボル").toTarget("_blank").toString();
上の処理は次のようなHTMLテキストを出力します。（シンボルの出力先設定は標準テンプレートと同一と仮定）
<a href="./symbols/MySymbol.html" target="_blank" >マイシンボル</a>
- Linkオブジェクトを正常に動作させるには、 publish 関数に conf プロパティが存在していなくてはなりません。詳細はこちらを参照してください。
| コンストラクタ | 説明 |
|---|---|
| new Link() | Linkオブジェクトを作成します。 |
| プロパティ | 説明 |
|---|---|
|
<String> Link.base |
相対パスでリンク先を指定する際のベースパス |
|
<JSDOC.SymbolSet> Link.symbolSet |
シンボルセット。ネームパスからシンボルを取得するために使用します。Linkクラスをテンプレートから使用する場合、 publish() 関数が受け取った SymbolSet オブジェクトを事前にこのプロパティに設定しておく必要があります。 |
| メソッド | 説明 |
|---|---|
|
<Link> object.target(targetName) |
<a>タグのtarget属性の値を設定します。 |
|
<Link> object.toFile(filePath) |
リンク先として通常のファイルパスを設定します。 |
|
<Link> object.toSrc(fileName) |
リンク先としてソースファイル名を設定します。これはハイライトされたソースコードファイルへのリンクとなります。 |
|
<String> object.toString() |
オブジェクトの文字列表現として、現在の設定に基づいて作成された<a>タグのHTMLテキストを返します。 |
|
<Link> object.toSymbol(alias) |
リンク先としてシンボル（のネームパス）を設定します。 |
|
<Link> object.withText(text) |
リンク表示されるテキストを設定します。設定しない場合はリンク先のパスが使われます。 |
関数
| 関数 | 説明 |
|---|---|
|
<Object> copy(obj) |
引数で渡されたオブジェクトに対して、「深いコピー」による複製を作成して返します。ただし引数がオブジェクトでなかった場合は値をそのまま返します。 この関数を使用する場合、循環参照による無限ループに注意してください。 |
|
<Boolean> defined(value) |
引数 value が未定義(undefined)でなければtrueを返します。 |
|
<Boolean> isUnique(array) |
引数で渡された配列の要素に重複がなければtrueを返します。 |
|
<void> Namespace(name[,func]) |
名前空間階層を作成します。引数 name には"ns1.ns2.ns3"のように、名前空間の階層を"."区切りで指定します。名前空間が既に存在していれば何もせず、存在していなければ新しい名前空間を作成します。第２引数 func は省略可能で、名前空間作成後に実行される関数を設定することができます。 |
組み込みクラスの拡張
ReqExp クラス
| メソッド | 説明 |
|---|---|
|
<String> RegExp.escapeMeta(str) |
引数で渡された文字列中に含まれる正規表現メタ文字を全て\でエスケープした文字列を返します。 |
String クラス
| メソッド | 説明 |
|---|---|
|
<Number[]> object.balance(opener,closer) |
この文字列中で開始文字
opener
と終了文字
closer
に囲まれる範囲を最大マッチで検索し、文字インデックス番号として返します。戻り値は数値の配列で、インデックス0が開始文字の番号を、インデックス1が終了文字の番号を表します。 文字が見つからないなど範囲を確定できなかった場合、戻り値の番号には全て-1が設定されます。 |
|
<String> object.trim() |
文字列の両端にある空白文字（スペースや改行）を除去した文字列を返します。 |
関連項目
