JSDoc 中文网

教程

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

🌐 JSDoc allows you to include tutorials alongside your API documentation. You can use this feature to provide detailed instructions for using your API, such as a "getting started" guide or a step-by-step process for implementing a feature.

添加教程

🌐 Adding tutorials

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

🌐 To add tutorials to your API documentation, run JSDoc with the --tutorials or -u option, and provide a directory that JSDoc should search for tutorials. For example:

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

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

🌐 JSDoc searches the tutorials directory for files with the following extensions:

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

🌐 JSDoc also searches for JSON files that contain information about the titles, ordering, and hierarchy of your tutorials, as discussed in the following section.

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

🌐 JSDoc assigns an identifier to each tutorial. The identifier is the filename without its extension. For example, the identifier for /path/to/tutorials/overview.md is overview.

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

🌐 In tutorial files, you can use the {@link} and {@tutorial} inline tags to link to other parts of the documentation. JSDoc will automatically resolve the links.

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

🌐 Configuring titles, order, and hierarchy

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

🌐 By default, JSDoc uses the filename as the tutorial's title, and all tutorials are at the same level. You can use a JSON file to provide a title for each tutorial and indicates how the tutorials should be sorted and grouped in the documentation.

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

🌐 The JSON file must use the extension .json. In the JSON file, you can use the tutorial identifiers to provide two properties for each tutorial:

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

🌐 In JSDoc 3.2.0 and later, you can use the following formats for the JSON file:

  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 文件，使用教程标识符作为文件名。此方法已弃用，不应在新项目中使用。

🌐 You can also provide an individual .json file for each tutorial, using the tutorial identifier as the filename. This method is deprecated and should not be used for new projects.

链接到 API 文档中的教程

🌐 Linking to tutorials from API documentation

有多种方法可以从 API 文档链接到教程：

🌐 There are multiple ways to link to a tutorial from your API documentation:

@tutorial 块标签

🌐 @tutorial block tag

如果你在 JSDoc 注释中包含 @tutorial 块标签，生成的文档将包含指向你指定教程的链接。

🌐 If you include a @tutorial block tag in a JSDoc comment, the generated documentation will include a link to the tutorial you specify.

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

{@tutorial} 内联标签

🌐 {@tutorial} inline tag

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

🌐 You can also use the {@tutorial} inline tag to link to a tutorial within the text of another tag. By default, JSDoc will use the tutorial's title as the link text.

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