管理メニュー

JsDoc Toolkitを使う！

ダウンロード

最終更新：

aias-jsdoctoolkit

- view
管理者のみ編集可

トップページ >

ダウンロード

このページでは、管理人が作成したテンプレートとプラグインを公開します。

  • ここで公開されているプログラムの使用は商用・個人を問わず自由です。ただしそこから発生する結果について作成者は一切の責任を負わないものとします。
  • バグなどお気付きの点がありましたらこちらまでお願いします。

目次

テンプレート

  • テンプレートの指定方法については、こちらを参照してください。
  • 独自のテンプレートを作成する方法については、こちら以下を参照してください。

aias-frame

クラスリストページとクラス詳細ページをフレームで分割して表示する、JavaDocなどに近い出力形式のテンプレートです。

  • 機能
    • 左側のクラスリストを展開し、クラスメンバ（プロパティ、メソッドなど）を表示することができます。各項目は詳細ページへのリンクになっています。
  • ネームパスまたは名称（階層情報を含まない単純なクラス名やメソッド名など）で、クラスリストの表示内容をフィルタリングする機能を持っています。フィルタリングはキー入力があるたびにインクリメンタルに実行されるため、目的のクラスやクラスメンバを素早く検索することができます。
    • マッチング方式は前方一致と部分一致を選択できます。
    • フィルタリングのためのネームパスの区切り文字はスコープに関係なく "." です。例えばインスタンスメソッドでも classname.methodname のように入力してください。
  • 他のクラスから継承したクラスメンバの折りたたみ／展開表示の切り替えが可能です。
  • -pオプションでプライベートメンバを出力している場合、詳細ページの「プライベートメンバを隠す」チェックボックスのon/offでプライベートメンバの表示／非表示を切り替えることができます。
  • インタフェース／抽象クラス／静的クラスの宣言、@protectedタグ等の独自タグ、継承先クラスの出力など、symbolExtensionsプラグイン(バージョン1.2.0～)が提供する様々な拡張機能の表示をサポートします。
  • @exampleタグに記述されたサンプルコードを、ソースファイルHTMLと同じスタイルでハイライト表示します。
  • 説明文中に<code>タグで挿入されたソースコードを、「インライン」のサンプルコードとしてソースファイルHTMLと同じスタイルでハイライト表示します。
  • 「定義」項目のリンクやクラスメンバ名の右側に表示されているアイコンをクリックすると、ソースファイル内のそれらが定義された位置へ画面が移動します。
    • この機能を有効にするには、このページで配布している拡張されたpublishSrcHiliteプラグイン(バージョン1.1.0～)が導入されている必要があります。
    • 定義位置はドックコメントを元に判定されるため、その項目にドックコメントが付加されていない場合は位置不明としてソースファイルの先頭に移動します。
  • 独自の記法で、プロパティ付きの戻り値のドキュメント化をサポートします。
    @returnsタグの説明文が"."で始まっている場合、その値は直前の"."で始まっていない@returnsタグのプロパティとしてドキュメント化されます。コードの例とその出力結果は以下のとおりです。

    /**
     * 幅と高さを返す。
     * @returns {Object} サイズ情報を持つオブジェクト
     * @returns {Number} .width 幅
     * @returns {Number} .height 高さ
     */

    Rectangle.prototype.getSize = function() {

  • @linkタグにおいて記述された内容がネームパスと一致しなかった場合、それらを同一クラス内の他のメンバへのリンクと解釈し、クラス詳細ページ内への内部リンクを出力します。したがってクラス内の他のメンバへのものであれば、名称を記述するだけでリンクを作ることができます。ただし、以下の点に注意してください。
    • インスタンスメンバ以外の場合、ネームパスの区切りに使用されているプリフィックス（ ./-/event: ）をつけてください。これらのプリフィックスは出力時には取り除かれます。
    • リンクの作成はリンク先のメンバが実在するかどうかを考慮せずに機械的に行われます。
  • 概要ページの追加をサポートします。次の手順で作業してください。
    1. 概要ページに出力したい内容を@fileOverviewタグと同様の形式で独立したテキストファイルに記述し、保存します。
       ファイル名は任意ですが、文字エンコーディングは-eオプションと一致している必要があります。
    2. -Dオプションのoverviewプロパティに、作成したファイルのパスを指定します。
    • ファイルパスは絶対パスもしくはテンプレートディレクトリからの相対パスで指定してください。
    • 実在のファイルパスでなくても、-Dオプションのoverviewプロパティに false 以外の何らかの値が設定されていれば、デフォルトの概要ページが出力されます。
    • JsDoc Toolkitのバグにより、(1)のような":"を含むファイルパスはコマンドライン上の指定では正しく解釈されません。この問題を回避するため、aias-frameは(2)のようにパスの２文字目が"?"だった場合はそれを":"に置き換えてファイルを読み込むようになっています。尚、コンフィグファイルを使用している場合はこの問題は発生しません。

      (1)‐D="overview:c:\overview.js" (2)‐D="overview:c?\overview.js" --> c:\overview.js

    • 概要ページのドックコメント内では、@appNameタグという特殊なタグを使用できます。@appNameタグにはアプリケーション名を設定することが想定されており、その内容は概要ページやドキュメント全体のタイトルとして出力されます。（ただし-Dオプションのtitleプロパティが指定されている場合は、そちらが優先されます。）
    • デモページ#1で使用されている概要ページ用のドックコメントファイルをサンプルとしてこちらからダウンロードできます。
  • -Dオプションで以下のプロパティを使用できます。
    copyright コピーライト表示
    css CSSファイルのパスを指定し、テンプレートに独自のCSS定義を追加します。ファイルパスは絶対パスまたはテンプレートディレクトリからの相対パスで指定してください。
    CSSファイルの内容はテンプレートに含まれる全てのページに適用されます。
    lang ドキュメントで使用される言語を指定します。デフォルトは日本語です。
    ja : 日本語
    en : 英語
    overview 概要ページのソースとなるファイルを指定します。詳細は上の説明をご覧ください。
    title ドキュメントのタイトル
  • ドキュメント内の見出しなどで使用されているキーワードは keywords_ja.js 、 keywords_en.js 内にパラメータ化されており、簡単に変更することができます。


jsdoc-ja

標準テンプレートである"jsdoc"内のキャプションなどを日本語に置き換えたものです。ページ構成や機能はjsdocとほぼ同じです。

  • 機能
    • ソースコードには任意の文字エンコーディングを使用できます。
    • -Dオプションで以下のプロパティを使用できます。
      copyright コピーライト表示
      title ドキュメントのタイトル
    • 日本語化した部分は keywords.js 内にパラメータ化されており、簡単に変更することができます。


プラグイン

  • プラグインの詳細はこちらを参照してください。

一括ダウンロード

このページで公開されている全てのプラグインの最新バージョンをまとめてダウンロードできます。


additionalOptions --- いくつかのオプションを追加する

JsDoc Toolkitのコマンドラインオプションとして以下を追加します。これらは -D オプションによるカスタムオプションとして指定してください。

A trueを指定すると、名前が"_"から始まるメンバをprivateメンバとして扱いません。
anonymous trueを指定すると、無名関数を $anonymous という名前で出力します。
（通常、無名関数は出力されません。）
shortExplain trueを指定すると、生成されたシンボルの短い説明をログに出力します。

記述例

java -jar jsrun.jar app\run.js myscripts\ -D="A:true" -D="anonymous:true" -D="shortExplain:true" ...


browserObjects --- ブラウザ組み込みオブジェクトシンボルの自動生成

ドックコメントをwindowやdocumentなどブラウザ組み込みオブジェクトのメンバに対して記述したい場合があります。例えば下のようなときです。

/** 初期化処理を実行する。 */

window.onload = function() { .... };

しかし通常の処理では、上のドックコメントは出力されません。windowオブジェクトの定義がコード内に存在しないため、不正な記述とみなされるからです。@nameタグでwindowオブジェクトを定義することもできますが、やや煩雑です。browserObjectsプラグインは上のようなコードが存在すると、必要なオブジェクトのクラスシンボルを自動的に作成します。
このプラグインがサポートするブラウザ組み込みオブジェクトは以下のとおりです。

window, document, navigator, frames, screen, location, history


easyLink --- リンクを簡単に作成する

タグの説明文中のリンク作成をより簡単に記述できるようにするプラグインです。標準仕様では説明文中に@linkタグまたは<a>HTMLタグを直接書くことでリンクを作成しますが、このプラグインを適用するとリンク先を [[ と ]] で囲むだけでリンクを定義することができるようになります。 ※従来どおり@linkタグや<a>タグを直接記述することも可能です。

  • ダウンロード
  • 機能
    • リンク先のプロトコルがhttp/https/ftp、またはメールアドレスの場合、何もしなくてもリンクとして自動認識されます。 ただしリンク先文字列の両端にはスペースまたは改行をおいてください。
  • リンクを明示的に指定するには、リンク先を [[ と ]] で囲みます。それらはドキュメント出力時にプラグインによって<a>タグに置き換えられます。（URLかメールアドレスかはプラグインが自動的に判断します。）
    [[http://www12.atwiki.jp/aias-jsdoctoolkit/]] <a href="http://www12.atwiki.jp/aias-jsdoctoolkit/" >http://www12.atwiki.jp/aias-jsdoctoolkit/</a>
    [[aias@aias-wood.jp]] <a href="mailto:aias@aias-wood.jp" >aias@aias-wood.jp</a>
  • > を使用すると、リンクに表示するテキストを指定できます。
    [[JsDoc Toolkitを使う！>http://www12.atwiki.jp/aias-jsdoctoolkit/]] <a href="http://www12.atwiki.jp/aias-jsdoctoolkit/" >JsDoc Toolkitを使う！</a>
  • > の代わりに >> を使用すると、別ウィンドウで開くリンクを作成します。表示テキストを書かず >> を文頭にすると、（最初の例のように）URLを表示テキストとして使用します。
    [[JsDoc Toolkitを使う！>>http://www12.atwiki.jp/aias-jsdoctoolkit/]] <a href="http://www12.atwiki.jp/aias-jsdoctoolkit/" target="_blank" >JsDoc Toolkitを使う！</a>
    [[>>http://www12.atwiki.jp/aias-jsdoctoolkit/]] <a href="http://www12.atwiki.jp/aias-jsdoctoolkit/" target="_blank" >http://www12.atwiki.jp/aias-jsdoctoolkit/</a>
  • ネームパスを [[ と ]] で囲んで記述すると、それらはプラグインによって@linkタグに置き換えられます。
    [[TheClass#theMethod]] {@link TheClass#theMethod }


publishSrcHilite --- ソースファイルのハイライト処理

ソースファイルのハイライト処理を実行する標準プラグインpublishSrcHiliteを拡張し、より詳細なスタイル設定ができるようにしたものです。オリジナルのpublishSrcHilite.jsを上書きして使用してください。

  • ダウンロード
  • 機能
    • プラグインのソース内の JsHilite.styles オブジェクトの各プロパティの内容を書き換えることで、出力されるソースファイルのCSS設定を変更することができます。プロパティ名とその意味は下表のとおりです。
      body bodyタグのCSSスタイル
      keyWord JavaScriptキーワードのCSSスタイル
      docCmt ドックコメントのCSSスタイル
      docTag ドックコメント内のタグのCSSスタイル
      comment ドックコメントでない通常のコメントのCSSスタイル
      number 数値のCSSスタイル
      string 文字列のCSSスタイル
      regExp 正規表現のCSSスタイル
      lineNum 行番号のCSSスタイル
      selLineColor 選択行の行番号の文字列色
      selLineBgColor 選択行の行番号の背景色
    • プラグインのソース内の JsHilite.tabToSpace プロパティ値には、ソースファイル内のタブをいくつの半角スペースに置き換えるかを設定します。ただし0未満の値が設定された場合はタブがそのまま出力されます。
    • ソースファイル内でシンボルの記述された位置の行番号を、シンボルオブジェクトのプロパティとして追加します。ただし行の割り出しはドックコメントの位置を元に行われるため、ドックコメントがついていないシンボルでは番号は付加されません。
      このプラグインが適用された Symbol オブジェクトには以下のプロパティが追加されます。
      srcLineNum 行番号。不明な場合は-1。
      srcAnchor 出力されたソースファイルHTML内で、行番号の位置を表すアンカー名。（例："#line100"）
    • 出力されたソースファイルHTMLに対し上のsrcAnchorの値をアンカーとして指定した場合、該当する行をページの先頭にし、行番号を強調表示します。

symbolExtensions --- シンボルの機能拡張

Symbol オブジェクトにいくつかの機能追加を行うプラグインです。（最終的にドキュメントに出力されるためには、テンプレート側の対応が必要です）

  • ダウンロード
  • 機能
    • 独自タグの追加
      symbolExtensionsプラグインは下表に示す独自のタグをサポートします。タグの書き方はこちらのデモのソースコード表示を参考にしてください。
      タグ名 説明
      @abstract @privateや@finalタグのような書き方でクラスメンバに指定し、そのメンバが抽象メンバであり、継承クラスが実装しなければならないことを示します。@abstractタグが記述されたメンバを持つクラス（またはそれを継承し、抽象メンバを実装していないクラス）は自動的に抽象クラスとなります。
      @abstractタグが記述された Symbol オブジェクトには以下のプロパティが追加されます。
          - isAbstract 抽象メンバであればtrue
      @abstractClass @abstractClassタグは、そのシンボルが「抽象クラス」であることを示します。このタグは@classや@namespaceの位置に、それらの代わりに記述してください。
      なおこのタグが記述されていない場合でも、抽象メンバを持っているクラス（またはそれを継承し、抽象メンバを実装していないクラス）は自動的に抽象クラスとなります。
      抽象クラスとして定義された Symbol オブジェクトには以下のプロパティが追加されます。
          - isAbstractClass 抽象クラスであればtrue
      @implements クラスコンストラクタのドックコメント内に、そのクラスが実装しているインタフェースのネームパスを記述します。1つのタグにカンマ区切りで複数のネームパスを書くことができます。（もちろん複数のタグに分けてもかまいません）
      @implementsタグが記述された Symbol オブジェクトは、以下のプロパティを持ちます。
          - interfaces このクラスが実装しているインタフェースのネームパスの配列
      また、@implementsタグが記述されたクラスを継承したクラスの Symbol オブジェクトには以下のプロパティが追加されます。
          - inheritedInterfaces このクラスの継承元クラスが実装している全インタフェースのネームパスの配列
      @interface @interfaceタグは、そのシンボルが「インタフェース」であることを示します。このタグは@classや@namespaceの位置に、それらの代わりに記述してください。
      @interfaceタグが記述された Symbol オブジェクトには以下のプロパティが追加されます。
          - isInterface インタフェースであればtrue
          - implementers このインタフェースを実装しているクラスのネームパスの配列
      @protected @protectedタグは、そのメンバが自身と同じクラスか、それを継承したクラスのインスタンスからのみ参照可能であることを示します。@protectedタグは Symbol オブジェクトに isProtected プロパティとして反映されます。
      @readOnly プロパティに対して記述し、そのプロパティが読み取り専用であることを示します。
      @readOnlyタグが記述された Symbol オブジェクトには以下のプロパティが追加されます。
          - isReadOnly 読み取り専用であればtrue
      @staticClass @staticClassタグは、そのシンボルが（組み込みのMathオブジェクトのように）コンストラクタを持たずインスタンスを生成できない「静的クラス」であることを示します。このタグは@classや@namespaceの位置に、それらの代わりに記述してください。
      @staticClassタグが記述された Symbol オブジェクトには以下のプロパティが追加されます。
          - isStaticClass 静的クラスであればtrue
      @todo そのシンボルに関するTODOを記述するのに使用します。複数指定が可能です。
      タグの内容はシンボルの todo プロパティに配列として格納されます。
      @virtualClass @virtualClassタグは、そのシンボルが「仮想クラス」であることを示します。「仮想クラス」とはプロパティ値やメソッドパラメータ・戻り値などに無名オブジェクトが使用される場合に、ドキュメント作成の便宜上それを仮にクラスとして定義するものです。したがってソース上にこのクラスを定義する実体は存在せず、@nameタグによる宣言とともに使われます。このタグは@classや@namespaceの位置に、それらの代わりに記述してください。
      @virtualClassタグが記述された Symbol オブジェクトには以下のプロパティが追加されます。
          - isVirtualClass 仮想クラスであればtrue
  • @constantタグの書式拡張
    @constantタグの後にデータ型／定数値／説明文をまとめて記述できるよう、タグの仕様を拡張しました。以下に示すの例１、例２は同じ内容のドックコメントと解釈されます。（ただし標準仕様では定数値を記述する書式は無いため、そこだけは異なります。）
    データ型、定数値、説明文はそれぞれ省略することも可能です。ただし過去のバージョンとの互換性のため、例３のようにデータ型と定数値を両方省略した場合、タグの後ろに続くコメントは定数値を表すものと解釈されます。

    例１:

    /** @constant {Number}(0.05) 消費税の税率 */

    Taxes.CONSUMPTION_TAX = 0.05;

    例２:

    /**
     * 消費税の税率
     * @constant
     * @type Number
     */

    Taxes.CONSUMPTION_TAX = 0.05;

    例３:

    /** @constant 0.05 */

    Taxes.CONSUMPTION_TAX = 0.05;

    • 定数値は Symbol オブジェクトに constantValue プロパティとして反映されます。
  • @fieldタグの書式拡張#1
    @fieldタグを使用してプロパティのデータ型／初期値／説明文をまとめて記述できるよう、タグの仕様を拡張しました。以下に示すの例１、例２は同じ内容のドックコメントと解釈されます。データ型／初期値／説明文はそれぞれ省略可能です。

    例１:

    /** @field {Boolean}(false) 納税済みフラグ */

    this.isPaid = false;

    例２:

    /**
     * 納税済みフラグ
     * @type Boolean
     * @default false
     */

    this.isPaid= false;

  • @fieldタグの書式拡張#2
    @fieldタグを連続して記述することで、プロパティ値となっている無名オブジェクトのメンバを表現することができます。下の例のように説明文の後もしくは２つ目以降の@fieldタグの説明文が"."から開始されていれば、それに続く最初の空白文字まで無名オブジェクトのプロパティの名前、その後が説明文とみなされます。逆にこの書式に従っていない場合、２つ目以降の@fieldタグは無視されます。

    /**
     * テンプレート定義オブジェクト
     * @type Object
     * @field {String} .name テンプレート名
     * @field {String} .version バージョン
     * @field {String} .ext 出力ファイルの拡張子
     * @field {String} .outDir 出力ディレクトリ
     */

    publish.conf = {
        name:    "aias-frame",
        version: "1.5.0",
        ext:     ".html",
        outDir:  JSDOC.opt.d || SYS.pwd+"../out/aias-frame/"
    };

    • 上の例では省略されていますが、データ型の後ろに初期値を記述することも可能です。
    • パースされた@fieldタグ(DocTagオブジェクト)は１つ目の@fieldタグに追加される properties プロパティに配列として設定されます。DocTagオブジェクトの name プロパティにはコメントに記述したプロパティの名前が、"."を除去した形式で設定されます。
  • 継承先クラス情報の追加
    Symbol オブジェクトに inheritedTo プロパティが追加されます。このプロパティはこのシンボルを継承するシンボルのネームパスの配列です。
  • @propertyタグのバグ修正
    オリジナルの@propertyタグのパース処理に存在する、プロパティが全てスタティックメンバと判定されてしまうバグの修正です。


tagLineBreak --- １行に複数のタグを書けるようにする

標準仕様ではタグは行の先頭から記述することになっていますが、ドックコメントの行数が多くなって読みにくくなるときがあります。このプラグインを追加すると、行の途中からタグを複数記述できるようになります。ただしタグとタグの間には1つ以上のスペースを空けてください。


tagSynonyms --- タグに別名をつける

標準機能の一部として組み込まれているプラグインファイル"tagSynonyms.js"に、下表の別名定義を追記したものです。
ダウンロードしたファイルを既存ファイルに上書き保存してお使いください。また、あなた自身の別名を加え、更にカスタマイズすることをお勧めします。

  • ダウンロード
  • 追加された別名
    標準タグ名 別名
    @constant @final, @const
    @param @arg
「ダウンロード」をウィキ内検索
人気記事ランキング
  1. @fileOverview
  2. @lends
  3. ドックコメントの書き方
  4. @requires
  5. @memberOf
  6. @description
もっと見る
最近更新されたページ
もっと見る
目安箱バナー