@use JSDoc

教程

JSDoc 允许您在 API 文档中包含教程。您可以使用此功能为使用您的 API 提供详细说明，例如“入门”指南或实现功能的分步流程。

添加教程

要向您的 API 文档添加教程，请使用 --tutorials 或 -u 选项运行 JSDoc，并提供 JSDoc 应搜索教程的目录。例如

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

JSDoc 在教程目录中搜索具有以下扩展名的文件

JSDoc 还会搜索包含有关教程的标题、顺序和层次结构的信息的 JSON 文件，如下节所述。

JSDoc 为每个教程分配一个标识符。标识符是文件名，不带扩展名。例如，/path/to/tutorials/overview.md 的标识符是 overview。

在教程文件中，您可以使用 {@link} 和 {@tutorial} 内联标签链接到文档的其他部分。JSDoc 将自动解析链接。

配置标题、顺序和层次结构

默认情况下，JSDoc 使用文件名作为教程的标题，所有教程都处于同一级别。您可以使用 JSON 文件为每个教程提供标题，并指示如何在文档中对教程进行排序和分组。

JSON 文件必须使用扩展名 .json。在 JSON 文件中，您可以使用教程标识符为每个教程提供两个属性

在 JSDoc 3.2.0 及更高版本中，您可以对 JSON 文件使用以下格式

  1. 对象树，其中子教程在父教程的 children 属性中定义。例如，如果 tutorial1 有两个子教程 childA 和 childB，并且 tutorial2 与 tutorial1 处于同一级别且没有子教程

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

  2. 顶级对象，其属性都是教程对象，其中子教程按名称列在数组中。例如，如果 tutorial1 有两个子教程 childA 和 childB，并且 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 块标签，生成的文档将包含指向您指定的教程的链接。

使用 `@tutorial` 块标签
/**
 * Class representing a socket connection.
 *
 * @class
 * @tutorial socket-tutorial
 */
function Socket() {}

{@tutorial} 内联标签

您还可以使用 {@tutorial} 内联标签 在另一个标签的文本中链接到教程。默认情况下，JSDoc 将使用教程的标题作为链接文本。

使用 `{@tutorial}` 内联标签
/**
 * Class representing a socket connection. See {@tutorial socket-tutorial}
 * for an overview.
 *
 * @class
 */
function Socket() {}