チュートリアル

JSDocでは、APIドキュメントの横にチュートリアルを含めることができます。この機能を使用すると、APIの使用方法に関する詳細な手順（「入門」ガイドや機能を実装するためのステップバイステッププロセスなど）を記載できます。

チュートリアルの追加

APIドキュメントにチュートリアルを追加するには、--tutorialsまたは-uオプションを指定してJSDocを実行し、JSDocがチュートリアルを検索するディレクトリを指定します。たとえば、

jsdoc -u path/to/tutorials path/to/js/files

JSDocは、次の拡張子を持つファイルについて、チュートリアルディレクトリを検索します。

• .htm
• .html
• .markdown（マークダウンからHTMLに変換）
• .md（マークダウンからHTMLに変換）
• .xhtml
• .xml（HTMLとして扱われる）

JSDocは、以下で説明するチュートリアルのタイトル、順序、階層に関する情報を格納するJSONファイルも検索します。

JSDocは、各チュートリアルに識別子を割り当てます。識別子は、拡張子のないfilenameです。たとえば、/path/to/tutorials/overview.mdの識別子はoverviewです。

チュートリアルファイルでは、{@link}および{@tutorial}インラインタグを使用して、ドキュメントの他の部分にリンクすることができます。JSDocはリンクを自動的に解決します。

タイトル、順番、階層の設定

デフォルトでは、JSDocはファイル名をチュートリアルのタイトルとして使用し、すべてのチュートリアルを同じレベルにします。JSONファイルを使用すると、各チュートリアルのタイトルを指定し、ドキュメント内でチュートリアルをソートおよびグループ化する順序を示すことができます。

JSONファイルには、拡張子.jsonを使用する必要があります。JSONファイルでは、チュートリアル識別子を使用して各チュートリアルの2つのプロパティを指定できます。

• title：ドキュメントに表示するタイトル。
• children：チュートリアルの子供。

JSDoc 3.2.0以降では、JSONファイルに対して次の形式を使用できます。

1. 子供のチュートリアルが親のchildrenプロパティに定義された、オブジェクトのツリー。たとえば、tutorial1にchildAとchildBという2つの子供がおり、tutorial2はtutorial1と同レベルで子供がいない場合、

   {
       "tutorial1": {
           "title": "Tutorial One",
           "children": {
               "childA": {
                   "title": "Child A"
               },
               "childB": {
                   "title": "Child B"
               }
           }
       },
       "tutorial2": {
           "title": "Tutorial Two"
       }
   }
   

2. プロパティがすべてチュートリアルオブジェクトであり、子供のチュートリアルが配列内の名前でリストされた、最上位オブジェクト。たとえば、tutorial1にchildAとchildBという2つの子供がおり、tutorial2はtutorial1と同レベルで子供がいない場合、

   {
       "tutorial1": {
           "title": "Tutorial One",
           "children": ["childA", "childB"]
       },
       "tutorial2": {
           "title": "Tutorial Two"
       },
       "childA": {
           "title": "Child A"
       },
       "childB": {
           "title": "Child B"
       }
   }
   

チュートリアル識別子をファイル名として使用し、各チュートリアルに対して個々の.jsonファイルを指定することもできます。このメソッドは非推奨であり、新しいプロジェクトでは使用しないでください。

APIドキュメントからチュートリアルへのリンク

APIドキュメントからチュートリアルにリンクする方法はいくつかあります。

@tutorialブロックタグ

JSDocコメントに@tutorialブロックタグを含めると、生成されたドキュメントには指定したチュートリアルへのリンクが含まれます。

/**
 * Class representing a socket connection.
 *
 * @class
 * @tutorial socket-tutorial
 */
function Socket() {}

{@tutorial}インラインタグ

別のタグのテキスト内でチュートリアルにリンクするには、{@tutorial}インラインタグを使用することもできます。デフォルトでは、JSDocはチュートリアルのタイトルをリンクテキストとして使用します。

/**
 * Class representing a socket connection. See {@tutorial socket-tutorial}
 * for an overview.
 *
 * @class
 */
function Socket() {}