@use JSDoc

設定ファイルを使用した JSDoc の設定

設定ファイルのフォーマット

JSDoc の動作をカスタマイズするには、以下のいずれかのフォーマットの設定ファイルを JSDoc に提供します。

設定ファイルを使用して JSDoc を実行するには、-c コマンドラインオプションを使用します（例：jsdoc -c /path/to/conf.json または jsdoc -c /path/to/conf.js）。

以下の例は、JSDoc の Markdown プラグインを有効にする単純な設定ファイルを示しています。JSDoc の設定オプションについては、以下のセクションで詳しく説明します。

JSON 設定ファイル
{
    "plugins": ["plugins/markdown"]
}
JavaScript 設定ファイル
'use strict';

module.exports = {
    plugins: ['plugins/markdown']
};

JSON 設定ファイルのより包括的な例については、conf.json.EXAMPLE ファイルを参照してください。

デフォルトの設定オプション

設定ファイルを指定しない場合、JSDoc は以下の設定オプションを使用します。

{
    "plugins": [],
    "recurseDepth": 10,
    "source": {
        "includePattern": ".+\\.js(doc|x)?$",
        "excludePattern": "(^|\\/|\\\\)_"
    },
    "sourceType": "module",
    "tags": {
        "allowUnknownTags": true,
        "dictionaries": ["jsdoc","closure"]
    },
    "templates": {
        "cleverLinks": false,
        "monospaceLinks": false
    }
}

これは以下のことを意味します。

これらのオプションやその他のオプションについては、以下のセクションで説明します。

プラグインの設定

プラグインを有効にするには、JSDoc フォルダからの相対パスを plugins 配列に追加します。

たとえば、次の JSON 設定ファイルは、Markdown 形式のテキストを HTML に変換する Markdown プラグインと、各 doclet の概要を自動生成する「summarize」プラグインを有効にします。

プラグインを含む JSON 設定ファイル
{
    "plugins": [
        "plugins/markdown",
        "plugins/summarize"
    ]
}

詳細については、プラグインリファレンスを参照し、JSDoc に組み込まれているプラグインについては、JSDoc の plugins ディレクトリを参照してください。

設定ファイルに markdown オブジェクトを追加することで、Markdown プラグインを設定できます。詳細については、Markdown プラグインの設定を参照してください。

再帰の深さの指定

recurseDepth オプションは、JSDoc がソースファイルとチュートリアルを再帰的に検索する深さを制御します。このオプションは JSDoc 3.5.0 以降で使用できます。このオプションは、JSDoc に入力ファイルを再帰的に検索するように指示する -r コマンドラインフラグも指定した場合にのみ使用されます。

{
    "recurseDepth": 10
}

入力ファイルの指定

source オプションセットは、コマンドラインで JSDoc に指定されたパスと組み合わせて、JSDoc がドキュメントの生成に使用する入力ファイルのセットを決定します。

{
    "source": {
        "include": [ /* array of paths to files to generate documentation for */ ],
        "exclude": [ /* array of paths to exclude */ ],
        "includePattern": ".+\\.js(doc|x)?$",
        "excludePattern": "(^|\\/|\\\\)_"
    }
}

これらのオプションは、以下の順序で解釈されます。

  1. コマンドラインと source.include で指定されたすべてのパスから開始します。
  2. 手順 1 で見つかった各ファイルについて、正規表現 source.includePattern が存在する場合、ファイル名はそれと一致する必要があります。そうでない場合は無視されます。
  3. 手順 2 から残った各ファイルについて、正規表現 source.excludePattern が存在する場合、この正規表現に一致するファイル名は無視されます。
  4. 手順 3 から残った各ファイルについて、ファイルのパスが source.exclude にある場合、無視されます。

これら 4 つの手順の後、残りのすべてのファイルが JSDoc によって処理されます。

例として、次のファイル構造があるとします。

myProject/
|- a.js
|- b.js
|- c.js
|- _private
|  |- a.js
|- lib/
   |- a.js
   |- ignore.js
   |- d.txt

さらに、conf.json ファイルが次の例のようになっているとします。

{
    "source": {
        "include": ["myProject/a.js", "myProject/lib", "myProject/_private"],
        "exclude": ["myProject/lib/ignore.js"],
        "includePattern": ".+\\.js(doc|x)?$",
        "excludePattern": "(^|\\/|\\\\)_"
    }
}

myProject フォルダを含むファイルから jsdoc myProject/c.js -c /path/to/my/conf.json -r を実行すると、JSDoc は以下のファイルのドキュメントを生成します。

理由は次のとおりです。

  1. source.include とコマンドラインで指定されたパスを考慮すると、JSDoc は以下のファイルから開始します。
    • myProject/c.js (コマンドラインから)
    • myProject/a.js (source.include から)
    • myProject/lib/a.js、myProject/lib/ignore.js、myProject/lib/d.txt (source.include から、-r オプションを使用)
    • myProject/_private/a.js (source.include から)
  2. JSDoc は source.includePattern を適用し、.js、.jsdoc、または .jsx で終わらない myProject/lib/d.txt *以外* の上記のすべてのファイルを残します.
  3. JSDoc は source.excludePattern を適用し、myProject/_private/a.js を削除します.
  4. JSDoc は source.exclude を適用し、myProject/lib/ignore.js を削除します.

ソースタイプの指定

sourceType オプションは、JSDoc が JavaScript ファイルを解析する方法に影響します。このオプションは JSDoc 3.5.0 以降で使用できます。このオプションは、以下の値を受け入れます。

{
    "sourceType": "module"
}

コマンドラインオプションの設定ファイルへの組み込み

JSDoc の コマンドラインオプションの多くは、コマンドラインで指定する代わりに、設定ファイルに配置できます。これを行うには、関連するオプションの長い名前を、値をオプションの値に設定して、設定ファイルの opts セクションに追加します。

コマンドラインオプションを含む JSON 設定ファイル
{
    "opts": {
        "template": "templates/default",  // same as -t templates/default
        "encoding": "utf8",               // same as -e utf8
        "destination": "./out/",          // same as -d ./out/
        "recurse": true,                  // same as -r
        "tutorials": "path/to/tutorials", // same as -u path/to/tutorials
    }
}

source.include オプションと opts オプションを使用することで、JSDoc への引数のほぼすべてを設定ファイルに配置できるため、コマンドラインは次のように短縮されます。

jsdoc -c /path/to/conf.json

コマンドラインと設定ファイルの両方でオプションが指定されている場合、コマンドラインが優先されます.

タグとタグディクショナリの設定

tags のオプションは、どの JSDoc タグが許可されるか、および各タグがどのように解釈されるかを制御します.

{
    "tags": {
        "allowUnknownTags": true,
        "dictionaries": ["jsdoc","closure"]
    }
}

tags.allowUnknownTags プロパティは、JSDoc が認識されないタグを処理する方法に影響します。このオプションを false に設定し、JSDoc が認識されないタグ (たとえば、@foo) を見つけた場合、JSDoc は警告をログに記録します。デフォルトでは、このオプションは true に設定されています。JSDoc 3.4.1 以降では、このプロパティを JSDoc が許可するタグ名の配列 (たとえば、["foo","bar"]) に設定することもできます.

tags.dictionaries プロパティは、JSDoc がどのタグを認識するか、および JSDoc が認識するタグをどのように解釈するかを制御します。JSDoc 3.3.0 以降では、2 つの組み込みタグディクショナリがあります.

デフォルトでは、両方のディクショナリが有効になっています。また、デフォルトでは、jsdoc ディクショナリが最初にリストされます。その結果、jsdoc ディクショナリが closure ディクショナリとは異なる方法でタグを処理する場合、jsdoc バージョンのタグが優先されます.

Closure Compiler プロジェクトで JSDoc を使用していて、Closure Compiler が認識しないタグの使用を避けたい場合は、tags.dictionaries 設定を ["closure"] に変更します。また、コア JSDoc タグを許可したいが、Closure Compiler 固有のタグが Closure Compiler が解釈するのと同じように解釈されるようにしたい場合は、この設定を ["closure","jsdoc"] に変更することもできます.

テンプレートの設定

templates のオプションは、生成されるドキュメントの外観と内容に影響します。サードパーティのテンプレートは、これらのオプションをすべて実装しているとは限りません。デフォルトテンプレートがサポートする追加オプションについては、JSDoc のデフォルトテンプレートの設定を参照してください.

{
    "templates": {
        "cleverLinks": false,
        "monospaceLinks": false
    }
}

templates.monospaceLinks が true の場合、インライン {@link} タグからのすべてのリンクテキストは等幅フォントでレンダリングされます.

templates.cleverLinks が true の場合、{@link asdf} は、asdf が URL の場合は通常のフォントでレンダリングされ、それ以外の場合は等幅フォントでレンダリングされます。たとえば、{@link http://github.com} はプレーンテキストでレンダリングされますが、{@link MyNamespace.myFunction} は等幅フォントになります.

templates.cleverLinks が true の場合、templates.monospaceLinks は無視されます.