JSDoc - это язык разметки, используемый для аннотирования исходного кода JavaScript с использованием комментариев. Аннотации обрабатывается различными инструментами для создания документации в доступных форматах, таких как HTML и Rich Text Format.
/** Это описание функции 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 доступен в официальной документации. Также есть дополнительные теги компилятора Closure. Рассмотрим основные теги.
/**
* Сложение двух чисел
* @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 {string} name - Имя пользователя
*/
function sayHello(name) {
alert('Привет ' + name);
}
/**
* Сложение двух чисел
* @param {number} a - Первое число
* @param {number} b - Второе число
* @returns {number} Сумма чисел a и b
*/
function add(a, b) {
return a + b;
}
/** @module User */
const defaultUserName = "НЛО";
/**
* Приветствие пользователя
* @param {string} name - Имя пользователя
*/
function sayHello(name) {
alert("Привет " + name || defaultUserName);
}
/** @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/> используется для перевода строки.
{
"plugins": [],
"recurseDepth": 10,
"source": {
"includePattern": ".+\\.js(doc|x)?$",
"excludePattern": "(^|\\/|\\\\)_"
},
"sourceType": "module",
"tags": {
"allowUnknownTags": true,
"dictionaries": ["jsdoc", "closure"]
},
"templates": {
"cleverLinks": false,
"monospaceLinks": false
}
}
Данная конфигурация подразумевает следующее:
{
"plugins": ["plugins/markdown"]
}
Список всех плагинов доступен тут.
{
"source": {
"include": [],
"exclude": [],
"includePattern": ".+\\.js(doc|x)?$",
"excludePattern": "(^|\\/|\\\\)_"
}
}
{
"opts": {
"destination": "./docs/",
"recurse": true
}
}
Подробнее про файл конфигурации можно прочитать тут.
JSDoc присваивает идентификатор каждому руководству. Идентификатор - это имя файла без расширения. Например, идентификатор для файла /path/to/tutorials/overview.md - это overview. Тег @tutorial создает ссылку на указанный вами идентификатор руководства. Пример:
/**
* Сокет-соединение.
*
* @tutorial socket-tutorial
*/
function Socket() {}
{
"tutorial1": {
"title": "Руководство 1",
"children": {
"sub-tutorial1": {
"title": "Подруководство 1"
},
"sub-tutorial2": {
"title": "Подруководство 2"
}
}
},
"tutorial2": {
"title": "Руководство 2"
}
}
habr.com
Начало работы
Создание проекта
Для создания проекта выполните следующие команды:- 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
Основные теги
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- для указанных каталогов рекурсивно сканировать подкаталоги.
Конфигурационный файл
Чтобы настроить поведение 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.
Генерация документации с использованием JSDoc
JSDoc - это язык разметки, используемый для аннотирования исходного кода JavaScript с использованием комментариев. Аннотации обрабатывается различными инструментами для создания документации в...
habr.com