教程

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.

添加教程

要在API文档中添加教程, 请使用 --tutorials 或 -u 选项运行JSDoc, 并提供JSDoc应搜索教程的目录. 例如:

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

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

• .htm

• .html

• .markdown (从Markdown转换为HTML)

• .md (从Markdown转换为HTML)

• .xhtml

• .xml (被视为HTML)

JSDoc还搜索包含有关教程的标题, 顺序和层次结构的信息的JSON文件, 如以下部分所述.

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

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.

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

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

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

• title: 要在文档中显示的标题.

• children: 教程的孩子们.

在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 块标签

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

Using the @tutorial block tag

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

{@tutorial} inline tag

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

Using the {@tutorial} inline tag

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