JSDoc - это язык разметки, используемый для аннотирования исходного кода JavaScript с использованием комментариев. Аннотации обрабатывается различными инструментами для создания документации в доступных форматах, таких как HTML и Rich Text Format.
Начало работы
Создание проекта
Для создания проекта выполните следующие команды:
-
mkdir learn-jsdoc && cd learn-jsdoc
- создание каталога проекта. -
npm init -y
- инициализация проекта. -
touch index.js
- создание файлаindex.js
Установка JSDoc
Выполните установку JSDoc одним из следующих способов:
-
Глобально:
sudo npm install -g jsdoc
-
Локально:
npm install -D jsdoc
Добавление комментариев
Для простоты весь код будем писать в файле index.js
. Комментарии JSDoc нужно размещать перед документируемым кодом. Каждый комментарий должен начинаться с последовательности /**
. Комментарии, начинающиеся с /*
, /***
и более 3 звезд, будут проигнорированы. Пример простейшей аннотации:
/** Это описание функции foo */
function foo() {
console.log("foo");
}
Для добавления описания напишите его в комментарии. Для указания дополнительной информации нужно использовать специальные теги. Например, если функция является конструктором, вы можете указать это, добавив тег @constructor.Тег @param позволяет указать тип, имя и описание параметра функции. Пример использования данных тегов:
/**
* Конструктор для создания книги
* @constructor
* @param {string} title - Название книги
* @param {string} author - Автор книги
*/
function Book(title, author) {
this.title = title;
this.author = author;
}
Генерация документации
Для генерации документации выполните одну из следующих команд в зависимости от того, как вы установили JSDoc:
-
Глобально:
jsdoc index.js
-
Локально:
./node_modules/.bin/jsdoc index.js
После этого в проекте появится каталог out
, содержащий сгенерированную документацию. Чтобы просмотреть её, откройте файл out/index.html
.
Основные теги
JSDoc поддерживает два типа тегов:
-
Блочные теги, которые находятся на верхнем уровне комментария JSDoc.
-
Встраиваемые теги, которые находятся в тексте блочного тега или описания.
Блочные теги начинаются со знака @
. За каждым блочным тегом должен следовать перевод строки, за исключением последнего блочного тега. Встраиваемые теги также начинаются со знака @
, но их текст должен быть заключен в фигурные скобки {}
. Если текст вашего тега включает фигурные скобки, вы должны экранировать их с помощью обратной косой черты . После встраиваемых тегов перевод строки не нужен.
Список тегов JSDoc доступен в официальной документации. Также есть дополнительные теги компилятора Closure. Рассмотрим основные теги.
Тег @description
Тег @description позволяет указать общее описание документируемого кода. Если общее описание идет в начале комментария (до использования других тегов), то тег @description
можно не писать:
/**
* Сложение двух чисел
* @param {number} a - Первое число
* @param {number} b - Второе число
*/
function add(a, b) {
return a + b;
}
Используя тег @description
, вы можете разместить описание в любом месте комментария:
/**
* Сложение двух чисел
* @param {number} a - Первое число
* @param {number} b - Второе число
* @description Сложение двух чисел
*/
function add(a, b) {
return a + b;
}
Тег @param
Тег @param позволяет указать имя (обязательно), тип и описание параметра функции. Синтаксис следующий: @param {Тип} Имя - Описание
. Тип параметра может быть встроенным типом JavaScript. Можно использовать выражения, чтобы указать, что параметр не допускает значения null
или он является массивом. Подробности смотрите в документации по тегу @type.
/**
* Приветствие пользователя
* @param {string} name - Имя пользователя
*/
function sayHello(name) {
alert('Привет ' + name);
}
Тег @returns
Тег @returns описывает значение, возвращаемое функцией. Синтаксис: @returns {Тип} Описание
.
/**
* Сложение двух чисел
* @param {number} a - Первое число
* @param {number} b - Второе число
* @returns {number} Сумма чисел a и b
*/
function add(a, b) {
return a + b;
}
Тег @module
Тег @module отмечает текущий файл как отдельный модуль. Все имена переменных и функций в файле являются членами модуля. Если имя модуля не указано, оно определяется путем и именем файла. Подробности использования модулей описаны далее.
/** @module User */
const defaultUserName = "НЛО";
/**
* Приветствие пользователя
* @param {string} name - Имя пользователя
*/
function sayHello(name) {
alert("Привет " + name || defaultUserName);
}
Пути к именам
При написании комментария JSDoc мы можем сослаться на переменную JavaScript. Чтобы это сделать, нужно указать путь к ней. Пути позволяют отличать переменные с одинаковым именем в разных модулях, а также методы экземпляров класса и статические методы.
Тег @link
Тег @link предназначен для добавления ссылки на переменную в определённом модуле. Данный тег является встраиваемым и имеет следующий синтаксис: {@link Путь к имени}
или [Текст ссылки]{@link Путь к имени}
. Если вы не укажите текст ссылки, JSDoc использует путь к имени в качестве текста ссылки. Рассмотрим на примере, создайте файл MyModule.js
со следующим содержимым:
/** @module MyModule */
/** Переменная модуля MyModule */
const variable = "Переменная модуля";
/** Функция модуля MyModule */
function foo() {
console.log("Функция модуля");
}
/**
* Конструктор MyClass
* @constructor
*/
function MyClass() {
/** Метод экземпляра класса MyClass */
this.foo = function () {
console.log("Метод экземпляра");
};
}
/** Статический метод класса MyClass */
MyClass.foo = function () {
console.log("Статический метод");
};
module.exports = {
MyClass,
variable,
foo,
};
В модуле MyModule
мы определили переменную, функцию и класс, который имеет метод экземпляра и статический метод. Далее, в файле index.js
, напишите следующее:
const { MyClass, variable, foo } = require("./MyModule");
/**
* Функция bar использует различный функционал модуля MyModule: <br/>
* [Переменная модуля]{@link module:MyModule~variable} <br/>
* [Функция модуля]{@link module:MyModule~foo} <br/>
* [Метод экземпляра]{@link module:MyModule~MyClass#foo} <br/>
* [Статический метод]{@link module:MyModule~MyClass.foo} <br/>
*/
function bar() {}
В описании функции bar
мы добавили ссылки на переменные и функции из модуля MyModule
. Синтаксис для указания пути к имени отличается только для методов экземпляра класса и статических методов. Тег <br/>
используется для перевода строки.
Аргументы командной строки
JSDoc поддерживает множество параметров командной строки, рассмотрим основные:
-
-c <value>, --configure <value>
- путь к файлу конфигурации JSDoc (рассмотрен далее). По умолчаниюconf.json
илиconf.json.EXAMPLE
в каталоге, где установлен JSDoc. -
-d <value>, --destination <value>
- путь к каталогу, содержащему сгенерированную документацию. По умолчанию./out
. -
-r, --recurse
- для указанных каталогов рекурсивно сканировать подкаталоги.
Пример использования: /path/to/jsdoc src -r -c /path/to/my/conf.json -d docs
. Данная команда создаёт документацию для файлов в каталоге ./src
и его подкаталогах, используя файл конфигурации /path/to/my/conf.json
, и сохраняет документацию в каталоге ./docs
.
Конфигурационный файл
Чтобы настроить поведение JSDoc, вы можете предоставить файл конфигурации в формате JSON или в виде модуля CommonJS.
Конфигурация по умолчанию
Если вы не укажете файл конфигурации, JSDoc использует следующие параметры:
{
"plugins": [],
"recurseDepth": 10,
"source": {
"includePattern": ".+\.js(doc|x)?$",
"excludePattern": "(^|\/|\\)_"
},
"sourceType": "module",
"tags": {
"allowUnknownTags": true,
"dictionaries": ["jsdoc", "closure"]
},
"templates": {
"cleverLinks": false,
"monospaceLinks": false
}
}
Данная конфигурация подразумевает следующее:
-
Плагины не используются (
plugins
). Подробнее о плагинах рассказано далее. -
Если рекурсия включена с помощью флага командной строки
-r
, JSDoc будет искать файлы не глубже 10 уровней (recurseDepth
). -
Будут обрабатываться только файлы, имеющие расширение
.js
,.jsdoc
и.jsx
(source.includePattern
). -
Любой файл или каталог, начинающийся с символа подчеркивания, будет проигнорирован (
source.excludePattern
). -
Поддерживается код, использующий модули ES2015 (
sourceType
). -
JSDoc позволяет использовать неизвестные теги (
tags.allowUnknownTags
). -
Включены как стандартные теги JSDoc, так и теги компилятора Closure (
dictionaries
). -
Встраиваемые теги
{@link}
отображаются в виде обычного текста (templates.cleverLinks
,templates.monospaceLinks
).
Использование плагинов
Чтобы включить плагин, добавьте его путь (относительно каталога JSDoc) в массив плагинов. Например, следующий файл конфигурации включает плагин Markdown, который преобразует текст в формате Markdown в HTML:
{
"plugins": ["plugins/markdown"]
}
Список всех плагинов доступен тут.
Указание входных файлов
Файл конфигурации, в сочетании с параметрами командной строки, определяет набор входных файлов, которые JSDoc использует для создания документации:
{
"source": {
"include": [],
"exclude": [],
"includePattern": ".+\.js(doc|x)?$",
"excludePattern": "(^|\/|\\)_"
}
}
-
source.include
- необязательный массив путей, содержащих файлы, для которых JSDoc должен генерировать документацию. Пути, указанные в командной строке, объединяются с этими путями. -
source.exclude
- необязательный массив путей, которые JSDoc должен игнорировать. -
source.includePattern
- необязательная строка, интерпретируемая как регулярное выражение. Все имена файлов должны соответствовать этому регулярному выражению для обработки JSDoc. -
source.excludePattern
- необязательная строка, интерпретируемая как регулярное выражение. Все файлы, соответствующие этому регулярному выражению, будет проигнорированы.
Отбор файлов, для которых будет сгенерированна документация, происходит в следующем порядке:
-
JSDoc начинает со всех путей, указанных в командной строке и в
source.include
. -
Если присутствует регулярное выражение
source.includePattern
, то для каждого файла, найденного на шаге 1, имя файла должно совпадать с ним, иначе оно игнорируется. -
Если присутствует регулярное выражение
source.excludePattern
, то для каждого файла, оставшегося после шага 2, любое имя файла, соответствующее этому регулярному выражению, игнорируется. -
Для каждого файла, оставшегося после шага 3, если его путь находится в
source.exclude
, он игнорируется.
Включение параметров командной строки в файл конфигурации
Вы можете поместить параметры командной строки в файл конфигурации:
{
"opts": {
"destination": "./docs/",
"recurse": true
}
}
Подробнее про файл конфигурации можно прочитать тут.
Руководства
Чтобы добавить руководства в документацию, запустите JSDoc с параметром --tutorials
или -u
и укажите каталог, в котором JSDoc должен искать руководства. Например: jsdoc -u path/to/tutorials path/to/js/files
. В каталоге руководств используются файлы со следующими расширениями: htm, html, markdown, md, xhtml, xml.
JSDoc присваивает идентификатор каждому руководству. Идентификатор - это имя файла без расширения. Например, идентификатор для файла /path/to/tutorials/overview.md
- это overview
. Тег @tutorial создает ссылку на указанный вами идентификатор руководства. Пример:
/**
* Сокет-соединение.
*
* @tutorial socket-tutorial
*/
function Socket() {}
Настройка заголовков, порядка и иерархии
По умолчанию JSDoc использует имя файла в качестве названия руководства, и все руководства находятся на одном уровне. Вы можете использовать файл конфигурации, чтобы указать заголовок для каждого руководства и определить, как руководства должны быть отсортированы и сгруппированы в документации. У каждого руководства есть два свойства:
-
title
- заголовок, отображаемый в документации. -
children
- руководства на следующем уровне иерархии.
Пример файла конфигурации руководств:
{
"tutorial1": {
"title": "Руководство 1",
"children": {
"sub-tutorial1": {
"title": "Подруководство 1"
},
"sub-tutorial2": {
"title": "Подруководство 2"
}
}
},
"tutorial2": {
"title": "Руководство 2"
}
}
Включение файла package.json в документацию
Файл package.json
содержат информацию, которая может быть полезна для документации проекта, например название проекта и номер версии. Есть два способа включить файл package.json
в документацию:
-
В путях к файлам JavaScript добавить путь к файлу
package.json
. -
Запустить JSDoc с параметром командной строки
-P
или--package
, указав путь к файлуpackage.json
.
Включение файла readme.md в документацию
Есть два способа включить файл readme.md
в документацию:
-
В путях к файлам JavaScript добавить путь к файлу
readme.md
. -
Запустить JSDoc с параметром командной строки
-R
или--readme
, указав путь к файлуreadme.md
.
Содержимое файла readme.md
будет отображаться на главной странице документации.
Автор:
nightzen