publish.js - JsDoc Toolkitを使う！

トップページ > カスタマイズ > テンプレート >

publish.js

publish.jsはテンプレート・システムの中心となるファイルで、ドキュメント出力のための実際の処理ロジックが記述されています。publish.jsはテンプレートフォルダの直下にに必ず publish.js というファイル名で存在していなくてはなりません。

目次

publish()関数

publish.jsには必ず publish() という名前の関数が定義されていなければなりません。

/** Called automatically by JsDoc Toolkit. */

function publish(symbolSet) {

}

上の例で、 publish 関数に symbolSet というパラメータが定義されていることに気づいたかもしれません。このパラメータは厳密には必須ではありませんが、従来からの慣習として付けることが推奨されています。
JsDoc Toolkitが全てのソースファイルをパースし終わると publish 関数が自動的に呼び出されます。そしてパースされた結果は JsDoc.SymbolSet 型の単一のオブジェクトにまとめられ、 publish 関数にパラメータとして渡されます。つまり publish 関数はSymbolSet内のシンボルを処理する何からのコードを含んでおり、それによって出力ファイルを作成することが想定されているのです。

SymbolSetオブジェクトを使う

JsDoc.SymbolSet はバージョン2.0から導入された新しいオブジェクトで、ファイルの垣根を越えてシンボル間の関係性を決定できるようになっています。テンプレート作成者にとってSymbolSetの機能の大部分は重要ではなく、この段階ではほとんどシンボルのコレクションにすぎません。それでも次の２つのメソッドはとても役に立つはずです。

function publish(symbolSet) {
    // ソースコード内の全シンボルの配列を取得します。
    var allSymbols = symbolSet.toArray();

    // ネームパスを指定してシンボルを取得します。
    var radiusSymbol = symbolSet.getSymbol("Circle#radius");

}

Symbolオブジェクトを使う

JsDoc.Symbol オブジェクトは、名前を持ち、ドキュメント化の対象となるコード内の要素 - 関数やその他の変数のような - を表します。シンボルオブジェクトはそのシンボルについて記された情報（明示的に記述されたものも、暗黙的に推測されたものも）を表す沢山のプロパティを持っています。ソースコード内で JsDoc.Symbol の全てのプロパティを利用できるように感じられることには価値があります。以下にいくつか例を示します。

function publish(symbolSet) {
    var getRadiusSymbol = symbolSet.getSymbol("Circle#getRadius");

    if (getRadiusSymbol.isPrivate) return;

    for (var i = 0; i < getRadiusSymbol.params; i++) {
         print("Param "+i+" is "+getRadiusSymbol.params[i]+".");
    }
}

シンボルのフィルタリング

JsDoc ToolkitはRhino1.7エンジンの上で動作します。そしてその環境では新しいMozillaによるJavaScriptの拡張を利用することができます。それらのうちの１つである filter メソッドは、シンボルのコレクションから特定の種類のシンボルを抜き出すのに最適です。

var allSymbols = symbolSet.toArray();

// privateなシンボルを取り出すフィルタを作成
var privateFilter = function($) {
    return $.isPrivate;
}

// privateなシンボルだけを取り出しました
var privateSymbols = allSymbols.filter(privateFilter);

filter メソッド以外にも、上記の拡張では配列の操作を行う様々なメソッドが追加されています。以下に簡単な一覧を示します。

indexOf	引数で指定されたデータの配列インデックス番号を返します。
lastIndexOf	引数で指定されたデータの、配列の末尾から数えたインデックス番号を返します。
every	引数で指定された関数を使って配列を評価し、全ての要素について関数がtrueを返せばtrueを、そうでなければfalseを返します。
filter	引数で指定された関数を使って配列を評価し、関数がtrueを返した要素だけを含む配列を返します。
forEach	引数で指定された関数を配列の全ての要素について実行します。ただしfilterメソッドなどと異なり、forEachでは関数の処理結果が何らかの評価に使われることはありません。
map	引数で指定された関数を配列の全ての要素について実行し、関数の戻り値の配列を返します。
some	引数で指定された関数を配列の先頭の要素から実行し、関数がfalseを返すまで次の要素をたどって処理を続けます。このメソッドは関数が1回でもtrueを返せばtrueを、そうでなければfalseを返します。

JsPlateにデータを渡す

あなたがシンボルやシンボルの配列に関して最もやりたいことは、それらをテンプレート（JsPlateマークアップを内部に含むJsPlateファイル）に渡すことでしょう。それには先ず、テンプレートファイルを元にJsPlateオブジェクトを生成する必要があります。

var myTemplate = new JSDOC.JsPlate("path/to/my/template.tmpl");

• .tmpl というファイル拡張子は通例に従っただけで、必須の条件ではありません。
  もしあなたが自分のテンプレートを作成しようと計画しており、それを標準の templates ディレクトリに保存させようと考えているなら、フルパスをハードコーディングするよりも app/run.js からの相対パスでファイルの位置を示したほうが良いでしょう。 app/run.js へのパスは SYS.pwd を参照すればどこからでも知ることができます。
  従って、より柔軟なテンプレートの参照方法は以下のようになります。
  var myTemplate = new JSDOC.JsPlate(SYS.pwd+"../templates/my/template.tmpl");
  これでJsPlateオブジェクトを取得できましたが、これにどのような仕事をさせるかはJsPlateファイルに書かれた内容に依存します。（JsPlateファイルの書き方については後述します。）以下の例では、1個のシンボルをテンプレートに渡しています。
  function publish(symbolSet) {
      var getRadiusSymbol = symbolSet.getSymbol("Circle#getRadius");
      var myTemplate = new JSDOC.JsPlate(SYS.pwd+"../templates/my/template.tmpl");
      var output = myTemplate.process(getRadiusSymbol);
  }
  process メソッドは渡されたデータとJsPlateファイル内の記述に基づいてドキュメント生成を実行し、結果を文字列として返します。

ドキュメントの出力

process メソッドを実行したことで目的の"output"--生成されたドキュメントの文字列--を得ることができましたので、最後にこれをファイルとして保存しなければなりません。 IO ネームスペースの静的メソッドを使えば、ファイルの操作はとても簡単です。

var output = myTemplate.process(mySymbol);
IO.saveFile("path/to/output/", "myFilename", output);

約束事として、JsDoc Toolkitによって作成された全ファイルは -d コマンドラインオプションで指定されたディレクトリ配下に出力されることになっています。それに従った出力例は以下のようになるでしょう。

var output = myTemplate.process(mySymbol);
var outDir = JSDOC.opt.d || SYS.pwd+"../out/";
IO.saveFile(outDir, "myFilename", output);

• IO 名前空間のメソッドリファレンスはこちらを参照してください。

静的ファイルのコピー

静的ファイルをテンプレートディレクトリから出力ディレクトリにコピーします。下の例はcssファイルを指定された出力ディレクトリへコピーします。

IO.copyFile(SYS.pwd+"../templates/myTemplate/static/mystyle.css", JSDOC.opt.d);

publish.confプロパティ

Linkクラスなど他の組み込みオブジェクトから参照されているため、publish()関数の静的メンバとしてconfプロパティを定義することを強く推奨します。※必須ではありません。
confプロパティの実体はテンプレートの設定情報を持つ無名オブジェクトで、以下のプロパティが定義されている必要があります。

<String>publish.conf.ext	出力ファイルの拡張子
<String>publish.conf.outDir	出力ディレクトリ
<String>publish.conf.templateDir	テンプレートディレクトリ
<String>publish.conf.symbolDir	シンボルドキュメントの出力ディレクトリパス
<String>publish.conf.srcDir	ハイライトされたソースドキュメントの出力ディレクトリパス

バージョン2.1.0の標準テンプレートのpublish.confプロパティは以下のように設定されています。

publish.conf = { // trailing slash expected for dirs
    ext:          ".html",
    outDir:       JSDOC.opt.d || SYS.pwd+"../out/jsdoc/",
    templatesDir: JSDOC.opt.t || SYS.pwd+"../templates/jsdoc/",
    symbolsDir:   "symbols/",
    srcDir:       "symbols/src/"
};

publish.js内での変数・関数宣言

publish.js（publish()関数内ではなく）で宣言された変数・関数はグローバルなスコープを持つオブジェクトとして全てのJsPlateファイル内から参照することが可能です。つまりJsPlateファイルの垣根を越えたグローバル変数や共通関数として利用できるのです。

標準テンプレート"jsdoc"のpublish.jsには他のテンプレートでも役に立ちそうな関数がいくつか定義されていますので、コピーして使うとよいでしょう。以下に簡単な一覧を示します。

<String>include(path)	テンプレートディレクトリを基準とする相対パスで指定されたファイルを読み込み、内容を文字列で返します。 この関数が正常に動作するためには publish.conf プロパティが必要です。
<Function>makeSortby(attribute)	シンボルを指定した属性でソートするための関数を返します。関数はシンボル配列の sort メソッドに引数として渡します。
<String>makeSignature(params)	パラメータを表すシンボルオブジェクトの配列を引数にとり、パラメータ名をカンマ区切りに列挙し、全体を()で囲った形式に整形して返します。
<void>makeSrcFile(path,srcDir[,name])	ハイライトされたソースコードドキュメントを出力します。pathにはファイルの絶対パス、srcDirには出力ディレクトリ、nameには拡張子を除く出力ファイル名（省略可）をそれぞれ指定します。 この関数が正常に動作するためには publish.conf プロパティが必要です。
<String>resolveLinks(str)	@linkタグを含むテキストを引数にとり、タグが示すシンボルへのリンクをaタグに置き換えたHTMLテキストに整形して返します。
<String>summarize(desc)	引数descで渡されたテキストデータから、最初の.（ピリオド）までの部分を抜き出して返します。ピリオドがなかった場合は全文を返します。

publish.jsの文字エンコーディング

JsDoc Toolkitがpublish.jsを読み込む際、publish.jsの文字エンコーディングは常に"ISO-8859-1"と解釈されるようです。このためpublish.js内のマルチバイト文字は（コメントも含め）文字化けやJavaScriptエラーの原因となる可能性がありますので、ご注意ください。

関連項目

• テンプレート
• JsPlateファイル　
• 組み込みオブジェクト リファレンス

---