Генерация документации с использованием JSDoc

JSDoc - это язык разметки, используемый для аннотирования исходного кода JavaScript с использованием комментариев. Аннотации обрабатывается различными инструментами для создания документации в доступных форматах, таких как HTML и Rich Text Format.

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

Создание проекта

Для создания проекта выполните следующие команды:

1. mkdir learn-jsdoc && cd learn-jsdoc - создание каталога проекта.

2. npm init -y - инициализация проекта.

3. touch index.js - создание файла index.js

Установка JSDoc

Выполните установку JSDoc одним из следующих способов:

1. Глобально: sudo npm install -g jsdoc

2. Локально: 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:

1. Глобально: jsdoc index.js

2. Локально: ./node_modules/.bin/jsdoc index.js

После этого в проекте появится каталог out, содержащий сгенерированную документацию. Чтобы просмотреть её, откройте файл out/index.html.

Основные теги

JSDoc поддерживает два типа тегов:

1. Блочные теги, которые находятся на верхнем уровне комментария JSDoc.

2. Встраиваемые теги, которые находятся в тексте блочного тега или описания.

Блочные теги начинаются со знака @. За каждым блочным тегом должен следовать перевод строки, за исключением последнего блочного тега. Встраиваемые теги также начинаются со знака @, но их текст должен быть заключен в фигурные скобки {}. Если текст вашего тега включает фигурные скобки, вы должны экранировать их с помощью обратной косой черты . После встраиваемых тегов перевод строки не нужен.

Список тегов 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 поддерживает множество параметров командной строки, рассмотрим основные:

1. -c <value>, --configure <value>- путь к файлу конфигурации JSDoc (рассмотрен далее). По умолчанию conf.json или conf.json.EXAMPLE в каталоге, где установлен JSDoc.

2. -d <value>, --destination <value>- путь к каталогу, содержащему сгенерированную документацию. По умолчанию ./out.

3. -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
  }
}

Данная конфигурация подразумевает следующее:

1. Плагины не используются (plugins). Подробнее о плагинах рассказано далее.

2. Если рекурсия включена с помощью флага командной строки -r, JSDoc будет искать файлы не глубже 10 уровней (recurseDepth).

3. Будут обрабатываться только файлы, имеющие расширение .js, .jsdoc и .jsx (source.includePattern).

4. Любой файл или каталог, начинающийся с символа подчеркивания, будет проигнорирован (source.excludePattern).

5. Поддерживается код, использующий модули ES2015 (sourceType).

6. JSDoc позволяет использовать неизвестные теги (tags.allowUnknownTags).

7. Включены как стандартные теги JSDoc, так и теги компилятора Closure (dictionaries).

8. Встраиваемые теги {@link} отображаются в виде обычного текста (templates.cleverLinks, templates.monospaceLinks).

Использование плагинов

Чтобы включить плагин, добавьте его путь (относительно каталога JSDoc) в массив плагинов. Например, следующий файл конфигурации включает плагин Markdown, который преобразует текст в формате Markdown в HTML:

{
  "plugins": ["plugins/markdown"]
}

Список всех плагинов доступен тут.

Указание входных файлов

Файл конфигурации, в сочетании с параметрами командной строки, определяет набор входных файлов, которые JSDoc использует для создания документации:

{
  "source": {
    "include": [],
    "exclude": [],
    "includePattern": ".+\.js(doc|x)?$",
    "excludePattern": "(^|\/|\\)_"
  }
}

1. source.include- необязательный массив путей, содержащих файлы, для которых JSDoc должен генерировать документацию. Пути, указанные в командной строке, объединяются с этими путями.

2. source.exclude- необязательный массив путей, которые JSDoc должен игнорировать.

3. source.includePattern- необязательная строка, интерпретируемая как регулярное выражение. Все имена файлов должны соответствовать этому регулярному выражению для обработки JSDoc.

4. source.excludePattern- необязательная строка, интерпретируемая как регулярное выражение. Все файлы, соответствующие этому регулярному выражению, будет проигнорированы.

Отбор файлов, для которых будет сгенерированна документация, происходит в следующем порядке:

1. JSDoc начинает со всех путей, указанных в командной строке и в source.include.

2. Если присутствует регулярное выражение source.includePattern, то для каждого файла, найденного на шаге 1, имя файла должно совпадать с ним, иначе оно игнорируется.

3. Если присутствует регулярное выражение source.excludePattern, то для каждого файла, оставшегося после шага 2, любое имя файла, соответствующее этому регулярному выражению, игнорируется.

4. Для каждого файла, оставшегося после шага 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 использует имя файла в качестве названия руководства, и все руководства находятся на одном уровне. Вы можете использовать файл конфигурации, чтобы указать заголовок для каждого руководства и определить, как руководства должны быть отсортированы и сгруппированы в документации. У каждого руководства есть два свойства:

1. title- заголовок, отображаемый в документации.

2. children- руководства на следующем уровне иерархии.

Пример файла конфигурации руководств:

{
  "tutorial1": {
    "title": "Руководство 1",
    "children": {
      "sub-tutorial1": {
        "title": "Подруководство 1"
      },
      "sub-tutorial2": {
        "title": "Подруководство 2"
      }
    }
  },
  "tutorial2": {
    "title": "Руководство 2"
  }
}

Включение файла package.json в документацию

Файл package.json содержат информацию, которая может быть полезна для документации проекта, например название проекта и номер версии. Есть два способа включить файл package.json в документацию:

1. В путях к файлам JavaScript добавить путь к файлу package.json.

2. Запустить JSDoc с параметром командной строки -P или --package, указав путь к файлу package.json.

Включение файла readme.md в документацию

Есть два способа включить файл readme.md в документацию:

1. В путях к файлам JavaScript добавить путь к файлу readme.md.

2. Запустить JSDoc с параметром командной строки -R или --readme, указав путь к файлу readme.md.

Содержимое файла readme.md будет отображаться на главной странице документации.