Учебные пособия

Содержание

• Добавление учебных пособий
• Настройка заголовков, порядка и иерархии
• Ссылка на учебные пособия из документации API
  • @tutorial блок-тег
  • {@tutorial} инлайновый тег

JSDoc позволяет включать учебные пособия вместе с документацией API. Вы можете использовать эту функцию для предоставления подробных инструкций по использованию вашего API, например, руководства «Первые шаги» или пошагового процесса реализации функции.

Добавление учебных пособий

Чтобы добавить учебные пособия в вашу документацию API, запустите JSDoc с параметром --tutorials или -u, и укажите директорию, в которой 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.

В файлах учебных пособий вы можете использовать {@link} и {@tutorial} инлайновые теги для ссылки на другие части документации. JSDoc автоматически разрешит ссылки.

Настройка заголовков, порядка и иерархии

По умолчанию 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 блок-тег

Если вы включите @tutorial блок-тег в комментарий JSDoc, сгенерированная документация будет содержать ссылку на указанное учебное пособие.

/**
 * 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() {}