教程

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:

• .htm

• .html

• .markdown（从 Markdown 转换为 HTML）

  ¥.markdown (converted from Markdown to HTML)

• .md（从 Markdown 转换为 HTML）

  ¥.md (converted from Markdown to HTML)

• .xhtml

• .xml（视为 HTML）

  ¥.xml (treated as HTML)

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:

• title：要在文档中显示的标题。

  ¥title: The title to display in the documentation.

• children：辅导班的子级们。

  ¥children: The children of the 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 处于同一级别并且没有子级：

   ¥A tree of objects, with child tutorials defined in the children property of their parent. For example, if tutorial1 has two children, childA and childB, and tutorial2 is at the same level as tutorial1 and has no children:

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

2. 一个顶层对象，其属性都是教程对象，子教程按名称在数组中列出。例如，如果 tutorial1 有两个子级，childA 和 childB，而 tutorial2 与 tutorial1 处于同一级别并且没有子级：

   ¥A top-level object whose properties are all tutorial objects, with child tutorials listed by name in an array. For example, if tutorial1 has two children, childA and childB, and tutorial2 is at the same level as tutorial1 and has no children:

   {
       "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 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.

/**

 * 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.

/**

 * Class representing a socket connection. See {@tutorial socket-tutorial}

 * for an overview.

 *  * @class
 */
function Socket() {}