Начало работы с JSDoc 3

Содержание

• Начало работы
• Добавление комментариев документации в код
• Генерация веб-сайта

Начало работы

JSDoc 3 — это генератор документации API для JavaScript, аналогичный Javadoc или phpDocumentor. Вы добавляете комментарии документации непосредственно в исходный код, прямо рядом с самим кодом. Инструмент JSDoc просканирует ваш исходный код и сгенерирует веб-сайт документации HTML для вас.

Добавление комментариев документации в код

Цель JSDoc — документировать API вашего приложения или библиотеки JavaScript. Предполагается, что вы захотите документировать такие вещи, как модули, пространства имён, классы, методы, параметры методов и так далее.

Комментарии JSDoc обычно должны размещаться непосредственно перед кодом, который документируется. Каждый комментарий должен начинаться с последовательности /**, чтобы быть распознанным анализатором JSDoc. Комментарии, начинающиеся с /*, /***, или более чем с 3 звёздочек, будут проигнорированы. Это функция, позволяющая подавлять обработку блоков комментариев.

/** This is a description of the foo function. */
function foo() {
}

Добавление описания простое — просто наберите желаемое описание в комментарии документации.

Можно использовать специальные «теги JSDoc», чтобы предоставить больше информации. Например, если функция является конструктором класса, вы можете указать это, добавив тег @constructor.

/**
 * Represents a book.
 * @constructor
 */
function Book(title, author) {
}

Можно использовать больше тегов для добавления дополнительной информации. Полный список тегов, распознаваемых JSDoc 3, см. на домашней странице.

/**
 * Represents a book.
 * @constructor
 * @param {string} title - The title of the book.
 * @param {string} author - The author of the book.
 */
function Book(title, author) {
}

Генерация веб-сайта

После того, как ваш код прокомментирован, вы можете использовать инструмент JSDoc 3 для генерации веб-сайта HTML из ваших исходных файлов.

По умолчанию JSDoc использует встроенную шаблонную "default", чтобы преобразовать документацию в HTML. Вы можете изменить этот шаблон, чтобы он соответствовал вашим потребностям, или создать совершенно новый шаблон, если это то, что вам нужно.

jsdoc book.js

Эта команда создаст директорию под названием out/ в текущем рабочем каталоге. Внутри этой директории вы найдёте сгенерированные страницы HTML.