JsDoc Toolkitを使う！

プラグインの追加

最終更新：2009年09月22日 10:30

aias-jsdoctoolkit

- view

管理者のみ編集可

プラグインの追加

JsDoc Toolokitのバージョン2から、ソースコードに対するパース処理に（結果がテンプレートに渡されるより前に実行される処理として）ユーザー独自の機能を挿入することができるようになりました。この仕組みはプラグインと呼ばれ、JsDoc Toolkitの動作をユーザーの希望にあわせて変更する便利で可搬性のある方法です。

このページは公式サイトのhttp://code.google.com/p/jsdoc-toolkit/wiki/Pluginsを元に作成しました。

インストール

プラグインのインターフェースはシンプルに設計されています。プラグイン使用時のインストール作業は、プラグインファイルをapp/pluginsディレクトリに保存すること－これだけです。JsDoc Toolkitを起動すると、プラグインは自動的にロード・実行されます。

管理人が作成したプラグインをこちらからダウンロードできます。
実際にapp/pluginsディレクトリの中を見ると分かりますが、いくつかの標準機能はプラグインとして実装されています。それらのソースを読むことでプラグインに対する理解はより深まるでしょう。

API

プラグインを記述する方法もまたシンプルです。まず新しいテキストファイルを作成します；名前は自由につけてかまいません。プラグインファイルの内容は、以下のパターンに従っている必要があります。

JSDOC.PluginManager.registerPlugin(
    "JSDOC.myPluginName",
    {
        onSymbol: function(symbol) {
            // modify properties of the symbol here
        }
    }
);

JSDOC.PluginManager.registerPluginメソッドの呼び出しは、以下の２つの引数をとります。

yourPluginName -- プラグインの登録名を文字列で指定します。どのような名前をつけてもかまいませんが、その時点で使用される全てのプラグインの登録名と重複してはなりません。上の例のように名前の各部分をドットで区切る方法がよく使われますが、この名前により何らかのオブジェクトへの参照が発生することはありません。簡単に"JSDOC-myPluginName"としたり、さらに別の名付け規則を使うことも可能です。
functionMap -- JsDoc Toolkitの処理内で発生するイベント名をプロパティに持つオブジェクトリテラルを指定します。プロパティの値にはイベント発生時に実行されるハンドラ関数を設定します。
上の例ではonSymbolイベントに対しハンドラを設定しています。このイベントはJsDoc ToolkitがSymbolオブジェクトを生成する度に発生し、その際にハンドラ関数も一緒に呼び出されます。

Function Mapを作る

Function MapはJsDoc Toolkitのイベントとイベント発生時に実行される関数を関連付けます。APIの例でonSymbolというイベント名は、Symbolオブジェクトが生成されるたびにハンドラ関数が実行されることを意味しています。このとき関数は引数として新しく生成されたSymbolオブジェクトを受け取りますが、関数内ではそのオブジェクトのプロパティを参照して記録したり、値を変更したり、またはプロパティを追加したり削除したり様々に操作することができます。

バージョン2.1.0の時点でJSDOC.PluginManagerによってサポートされているイベントは以下のとおりです。（カッコ内はハンドラ関数への引数を表します）

`onSymbol(symbol)`	新しい`Symbol`オブジェクトが生成された後に発生します。ハンドラには引数として生成された`Symbol`オブジェクトが渡されます。
`onDocCommentSrc(comment)`	処理中にドックコメントが見つかったときに、それがパースされる前に発生します。ハンドラには引数として`DocComment`オブジェクトが渡されます。`DocComment#src`プロパティには処理対象のドックコメント文字列が設定されているので、ここでその値を操作することでパース結果に影響を与えることができます。
`onDocCommentTags(DocComment)`	１つのドックコメントがパースされ、そこに含まれるタグオブジェクトが全て生成された後に発生します。ハンドラには引数として`DocComment`オブジェクトが渡されます。`DocComment#tags`プロパティには生成された`DocTag`オブジェクトの配列が設定されているので、ここでそのオブジェクトの値を操作することで処理結果に影響を与えることができます。
`onDocTagSynonym(tag)`	`DocTag`オブジェクトの生成中に、タグ名が`title`プロパティに設定された時点で発生します。この段階ではまだタグ名はドックコメントに記述されたままの状態であり、通常別名で記述されたタグ名を標準のものに置き換えるタイミングとして使用されます。ハンドラには引数として`DocTag`オブジェクトが渡されます。
`onDocTag(tag)`	１つの`DocTag`オブジェクトが生成された後に発生します。ハンドラには引数として生成された`DocTag`オブジェクトが渡されます。
`onInit(opt)`	JsDoc Toolkitの起動時、コマンドラインオプションがパースされた後に発生します。ハンドラには引数としてコマンドラインオプションをプロパティに持つ無名オブジェクト（`JSDOC.opt`と同じもの）が渡されるので、このオブジェクトのプロパティを操作することで処理結果に影響を与えることができます。
`onFunctionCall(info)`	パース中のソース内で、何らかの関数またはメソッドが実行された結果として定義が生成されている箇所が見つかった場合に発生します。特定のライブラリが求めるような特殊な記法に対し、パース処理の必要に応じてドックコメントやソースコードそのものの挿入を行うタイミングとして想定されています。ハンドラには引数として以下のプロパティを持つ無名オブジェクトが渡されます。 `name` -- 関数またはメソッドの名前 `arg1...n` -- パラメータをarg1～nまで番号付けしたもの `doc` -- ハンドラ側から、イベント後に処理中のコードに挿入されるコードテキストを設定します。 ※このイベントについては公式サイトにも情報が乏しく、管理人が推測して書きましたが内容に自信がありません。何か情報をお持ちの方がいらっしゃいましたらご教示くださいますようお願いいたします。
`onFinishedParsing(symbolSet)`	全てのソースのパースが完了したときに発生します。ハンドラには引数として`SymbolSet`オブジェクトが渡されます。

独自のイベントを定義する

JSDOC.PluginManagerは処理内から呼び出されたイベント名を持つプラグインを検索し、関数を実行しているだけで、固有のイベント定義は持っていません。従って実際には呼び出し側のコードさえ存在すれば、誰でも独自のイベントを定義することができます。
具体的な利用法としては、テンプレート内に独自のイベント呼び出しコードを記述し、それをイベントとしてテンプレート利用者に公開するということが考えられます。標準テンプレートである"jsdoc"でもonPublishSrcというイベントが定義され、ハイライトされたソースコードをHTMLテキストとして生成するのに使用されています。

イベントの呼び出しはJSDOC.PluginManager.runメソッドをパラメータにイベント名とハンドラへの引数を指定して実行するだけです。ハンドラ引数にオブジェクトを渡せば、ハンドラ側でプロパティに設定された値を取得することもできます。