@use JSDoc

JSDocプラグインについて

プラグインの作成と有効化

新しいJSDocプラグインを作成して有効にするには、2つのステップが必要です。

  1. プラグインコードを含むJavaScriptモジュールを作成します。
  2. JSDocの設定ファイルのplugins配列にそのモジュールを含めます。絶対パスまたは相対パスを指定できます。相対パスを使用する場合、JSDocは、現在の作業ディレクトリ、設定ファイルが置かれているディレクトリ、JSDocディレクトリの順にプラグインを検索します。

たとえば、現在の作業ディレクトリのplugins/shout.jsファイルにプラグインが定義されている場合、JSDoc設定ファイルのplugins配列に文字列plugins/shoutを追加します。

JSDocの設定ファイルへのプラグインの追加
{
    "plugins": ["plugins/shout"]
}

JSDocは、設定ファイルにリストされている順にプラグインを実行します。

JSDoc 3プラグインの作成

JSDoc 3のプラグインシステムは、解析プロセスを広範囲に制御できます。プラグインは、次のいずれかを実行することにより、解析結果に影響を与える可能性があります。

イベントハンドラ

最高レベルでは、プラグインはJSDocが発火する特定の名前付きイベントのハンドラを登録できます。JSDocは、イベントオブジェクトをハンドラに渡します。プラグインモジュールは、次のようにハンドラを含むhandlersオブジェクトをエクスポートする必要があります。

'newDoclet'イベントのイベントハンドラプラグイン
exports.handlers = {
    newDoclet: function(e) {
        // Do something when we see a new doclet
    }
};

JSDocは、基盤となるコードと同じ順序でイベントを発火します。

イベントハンドラプラグインは、イベントオブジェクトにstopPropagationプロパティ（e.stopPropagation = true）を設定することにより、後続のプラグインの実行を停止できます。プラグインは、preventDefaultプロパティ（e.preventDefault = true）を設定することにより、イベントの発火を停止できます。

イベント: parseBegin

parseBeginイベントは、JSDocがソースファイルのロードと解析を開始する前に発火します。プラグインは、イベントの内容を変更することにより、JSDocが解析するファイルを制御できます。

注: このイベントは、JSDoc 3.2以降で発火します。

イベントオブジェクトには、次のプロパティが含まれています。

イベント: fileBegin

fileBeginイベントは、パーサーがファイルを解析しようとするときに発火します。プラグインは、必要に応じてこのイベントを使用してファイルごとの初期化をトリガーできます。

イベントオブジェクトには、次のプロパティが含まれています。

イベント: beforeParse

beforeParseイベントは、解析が開始される前に発火します。プラグインは、このメソッドを使用して、解析されるソースコードを変更できます。たとえば、プラグインはJSDocコメントを追加したり、有効なJavaScriptではない前処理タグを削除したりできます。

イベントオブジェクトには、次のプロパティが含まれています。

以下は、関数用の仮想コメントをソースに追加して、ドキュメントに解析および追加されるようにする例です。これは、ユーザーが利用できるが、ドキュメント化されるソースコードには表示されない可能性のあるメソッド（外部スーパークラスによって提供されるメソッドなど）をドキュメント化するために実行される場合があります。

例
exports.handlers = {
    beforeParse: function(e) {
        var extraDoc = [
            '/**',
            ' * Function provided by a superclass.',
            ' * @name superFunc',
            ' * @memberof ui.mywidget',
            ' * @function',
            ' */'
        ];
        e.source += extraDoc.join('\n');
    }
};

イベント: jsdocCommentFound

jsdocCommentFoundイベントは、JSDocコメントが見つかるたびに発火します。コメントは、任意のコードに関連付けられている場合と、そうでない場合があります。このイベントを使用して、処理される前にコメントの内容を変更する場合があります。

イベントオブジェクトには、次のプロパティが含まれています。

イベント: symbolFound

symbolFoundイベントは、パーサーがドキュメント化する必要がある可能性のあるコード内のシンボルに遭遇したときに発火します。たとえば、パーサーは、ソースファイル内の各変数、関数、およびオブジェクトリテラルのsymbolFoundイベントを発火します。

イベントオブジェクトには、次のプロパティが含まれています。

イベント: newDoclet

newDocletイベントは、最高レベルのイベントです。新しいドクレットが作成されたときに発火します。これは、JSDocコメントまたはシンボルが処理され、テンプレートに渡される実際のドクレットが作成されたことを意味します。

イベントオブジェクトには、次のプロパティが含まれています。

ドクレットのプロパティは、ドクレットが表すコメントまたはシンボルによって異なる場合があります。よく見られる一般的なプロパティには、次のものがあります。

JSDocがコードに対して生成するドクレットを確認するには、-Xコマンドラインオプションを使用してJSDocを実行します。

以下は、説明を強調するnewDocletハンドラの例です。

例
exports.handlers = {
    newDoclet: function(e) {
        // e.doclet will refer to the newly created doclet
        // you can read and modify properties of that doclet if you wish
        if (typeof e.doclet.description === 'string') {
            e.doclet.description = e.doclet.description.toUpperCase();
        }
    }
};

イベント: fileComplete

fileCompleteイベントは、パーサーがファイルの解析を完了したときに発火します。プラグインは、このイベントを使用してファイルごとのクリーンアップをトリガーできます。

イベントオブジェクトには、次のプロパティが含まれています。

イベント: parseComplete

parseCompleteイベントは、JSDocが指定されたすべてのソースファイルの解析を完了した後に発火します。

注: このイベントは、JSDoc 3.2以降で発火します。

イベントオブジェクトには、次のプロパティが含まれています。

イベント: processingComplete

processingCompleteイベントは、JSDocが継承および借用されたシンボルを反映するように解析結果を更新した後に発火します。

注: このイベントは、JSDoc 3.2.1以降で発火します。

イベントオブジェクトには、次のプロパティが含まれています。

タグの定義

タグをタグ辞書に追加することは、ドキュメントの生成に影響を与える中レベルの方法です。newDocletイベントがトリガーされる前に、JSDocコメントブロックが解析されて、説明と存在する可能性のあるJSDocタグが決定されます。タグが見つかった場合、タグ辞書で定義されていると、ドクレットを変更する機会が与えられます。

プラグインは、defineTags関数をエクスポートすることにより、タグを定義できます。その関数には、次のようにタグを定義するために使用できる辞書が渡されます。

例
exports.defineTags = function(dictionary) {
    // define tags here
};

辞書

辞書は、次のメソッドを提供します。

タグのonTaggedコールバックは、ドクレットまたはタグの内容を変更できます。

onTaggedコールバックの定義
dictionary.defineTag('instance', {
    onTagged: function(doclet, tag) {
        doclet.scope = "instance";
    }
});

defineTagメソッドは、タグの同義語を宣言するために使用できるsynonymメソッドを持つTagオブジェクトを返します。

タグの同義語の定義
dictionary.defineTag('exception', { /* options for exception tag */ })
    .synonym('throws');

ノードビジター

最下位レベルでは、プラグイン作成者は、各ノードを訪問するノードビジターを定義することにより、抽象構文木（AST）の各ノードを処理できます。ノードビジタープラグインを使用すると、コメントを変更し、任意のコードに対してパーサーイベントをトリガーできます。

プラグインは、次のようにvisitNode関数を含むastNodeVisitorオブジェクトをエクスポートすることにより、ノードビジターを定義できます。

例
exports.astNodeVisitor = {
    visitNode: function(node, e, parser, currentSourceName) {
        // do all sorts of crazy things here
    }
};

この関数は、次のパラメーターを持つ各ノードで呼び出されます。

実行する

ノードビジターを実装する主な理由は、通常はドキュメント化されないもの（クラスを作成する関数呼び出しなど）をドキュメント化したり、ドキュメント化されていないコードのドキュメントを自動生成したりできるようにするためです。たとえば、プラグインは、イベントが発火することを意味する_triggerメソッドへの呼び出しを探し、そのイベントのドキュメントを生成する可能性があります。

処理を実行するには、visitNode関数はイベントパラメータのプロパティを変更する必要があります。一般的に、目的はコメントを構築し、イベントを発火させることです。パーサーがすべてのノードビジターにノードを確認させた後、イベントオブジェクトにcommentプロパティとeventプロパティがあるかどうかを確認します。両方がある場合、eventプロパティで指定されたイベントが発火します。イベントは通常symbolFoundまたはjsdocCommentFoundですが、理論的には、プラグインは独自のイベントを定義して処理することができます。

イベントハンドラープラグインと同様に、ノードビジタープラグインは、イベントオブジェクトにstopPropagationプロパティを設定することによって、後続のプラグインの実行を停止できます（e.stopPropagation = true）。プラグインは、preventDefaultプロパティを設定することでイベントの発火を停止できます（e.preventDefault = true）。

エラーの報告

プラグインでエラーを報告する必要がある場合は、jsdoc/util/loggerモジュールの次のいずれかのメソッドを使用します。

これらのメソッドを使用すると、単にエラーをスローするよりもユーザーエクスペリエンスが向上します。

注意：エラーの報告にjsdoc/util/errorモジュールを使用しないでください。このモジュールは非推奨であり、将来のバージョンのJSDocで削除されます。

致命的ではないエラーの報告
var logger = require('jsdoc/util/logger');

exports.handlers = {
    newDoclet: function(e) {
        // Your code here.

        if (somethingBadHappened) {
            logger.error('Oh, no, something bad happened!');
        }
    }
};