Плагин eslint-plugin-jsdoc

Назначение eslint-plugin-jsdoc

Плагин eslint-plugin-jsdoc предназначен для анализа и проверки корректности JSDoc-комментариев в JavaScript-коде. Он расширяет возможности ESLint, добавляя набор правил, ориентированных на структуру, полноту и согласованность документации, встроенной непосредственно в исходный код. Основная задача заключается в поддержании единообразного формата документации функций, методов, классов и модулей, а также в предотвращении расхождений между фактической реализацией и описанием API.

JSDoc используется как стандарт документирования в JavaScript-проектах, особенно в библиотечном и инфраструктурном коде. При отсутствии контроля качества документации легко возникают ситуации, когда параметры, возвращаемые значения или типы устаревают и перестают соответствовать коду. Плагин решает эту проблему на уровне статического анализа.

Установка и подключение

Плагин устанавливается как обычная зависимость проекта:

npm install eslint-plugin-jsdoc --save-dev

После установки он подключается в конфигурации ESLint:

{
  "plugins": ["jsdoc"]
}

Далее активируются правила:

{
  "extends": ["plugin:jsdoc/recommended"]
}

Рекомендуемый пресет включает базовый набор проверок, обеспечивающих согласованность документации без избыточной строгости.

Поддерживается также ручная конфигурация:

{
  "plugins": ["jsdoc"],
  "rules": {
    "jsdoc/require-jsdoc": "warn",
    "jsdoc/check-alignment": "error"
  }
}

Структура правил eslint-plugin-jsdoc

Плагин состоит из набора правил, сгруппированных по типам проверок:

  • проверка наличия JSDoc у сущностей
  • валидация структуры комментариев
  • контроль типов и ссылок
  • синтаксическая корректность тегов
  • соответствие документации сигнатурам функций

Каждое правило работает независимо и может быть включено или отключено точечно.

require-jsdoc

Правило jsdoc/require-jsdoc контролирует наличие JSDoc-комментариев у заданных конструкций: функций, методов классов, экспортируемых сущностей.

Типичная конфигурация:

{
  "jsdoc/require-jsdoc": [
    "error",
    {
      "publicOnly": true,
      "contexts": ["FunctionDeclaration", "MethodDefinition"]
    }
  ]
}

Поведение правила зависит от контекста. При включении publicOnly проверка ограничивается экспортируемыми или публичными элементами, что снижает шум в утилитарных внутренних функциях.

Пример нарушения:

function sum(a, b) {
  return a + b;
}

Исправленный вариант:

/**
 * Суммирует два числа
 * @param {number} a
 * @param {number} b
 * @returns {number}
 */
function sum(a, b) {
  return a + b;
}

require-param

Правило jsdoc/require-param проверяет наличие описаний всех параметров функции в JSDoc-блоке. Оно сопоставляет параметры сигнатуры с тегами @param.

Конфигурация:

{
  "jsdoc/require-param": "error"
}

Поддерживается строгая проверка соответствия количества и имен параметров.

Пример несоответствия:

/**
 * Формирует строку
 * @param {string} value
 */
function build(value, suffix) {
  return value + suffix;
}

В данном случае отсутствует описание suffix, что считается ошибкой.

require-returns

Правило jsdoc/require-returns контролирует наличие описания возвращаемого значения через тег @returns.

Конфигурация:

{
  "jsdoc/require-returns": "error"
}

Особенно важно для функций, где тип возвращаемого значения не очевиден из контекста.

Пример:

/**
 * Проверяет значение
 */
function isValid(value) {
  return value != null;
}

Корректный вариант:

/**
 * Проверяет значение
 * @returns {boolean}
 */
function isValid(value) {
  return value != null;
}

check-alignment

Правило jsdoc/check-alignment отвечает за форматирование блоков JSDoc. Оно проверяет выравнивание звездочек, пробелов и структуры строк внутри комментария.

Пример нарушения:

/**
* Некорректное выравнивание
*/
function test() {}

Исправленный вариант:

/**
 * Корректное выравнивание
 */
function test() {}

Несмотря на визуальную простоту, это правило играет значительную роль в поддержании единообразного стиля в больших кодовых базах.

no-undefined-types

Правило jsdoc/no-undefined-types контролирует использование типов, не определённых в проекте или в стандартной среде.

Пример ошибки:

/**
 * @param {UserModel} user
 */
function save(user) {}

Если UserModel не определён в области видимости или не импортирован, фиксируется нарушение.

Правило полезно при интеграции с TypeScript-проектами, где JSDoc может дублировать типизацию. В таких случаях оно помогает избежать расхождения между TypeScript и документацией.

require-description

Правило jsdoc/require-description требует наличия текстового описания в JSDoc-блоке. Оно предотвращает появление формальных, но пустых комментариев.

Пример:

/**
 * @param {number} x
 * @returns {number}
 */
function square(x) {
  return x * x;
}

Такой комментарий считается неполным, поскольку отсутствует смысловое описание функции.

Корректный вариант:

/**
 * Возводит число в квадрат
 * @param {number} x
 * @returns {number}
 */
function square(x) {
  return x * x;
}

Теговая структура и строгая проверка JSDoc

eslint-plugin-jsdoc анализирует не только наличие тегов, но и их корректное сочетание. Проверяются:

  • порядок тегов
  • допустимые комбинации (@param, @returns, @throws)
  • корректность типов
  • согласованность имен параметров
  • отсутствие дублирования тегов

Это позволяет рассматривать JSDoc как формализованный контракт API, а не как свободный текстовый комментарий.

Интеграция с TypeScript

При использовании TypeScript часть функциональности JSDoc дублируется системой типов. Однако eslint-plugin-jsdoc сохраняет значение в нескольких сценариях:

  • проекты с частичной миграцией на TypeScript
  • генерация документации из JSDoc
  • библиотеки, распространяемые в виде JavaScript с типовыми аннотациями
  • контроль публичного API без включенного строгого TS-режима

В таких конфигурациях часто отключаются правила проверки типов, но сохраняются правила структуры и наличия описаний.

{
  "rules": {
    "jsdoc/no-types": "off",
    "jsdoc/require-description": "error",
    "jsdoc/check-alignment": "error"
  }
}

Расширенные сценарии использования

В крупных кодовых базах плагин используется для стандартизации документации API. Часто задаются строгие политики:

  • обязательное описание всех экспортируемых функций
  • запрет неполных JSDoc-блоков
  • контроль именования параметров
  • унификация типов данных
  • обязательные @throws для функций с выбросами исключений

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

/**
 * Выполняет безопасное деление двух чисел
 * @param {number} a - делимое
 * @param {number} b - делитель
 * @returns {number} результат деления
 * @throws {Error} при делении на ноль
 */
function safeDivide(a, b) {
  if (b === 0) {
    throw new Error("Division by zero");
  }
  return a / b;
}

Механизмы подавления проверок

Плагин поддерживает локальное отключение правил:

// eslint-disable-next-line jsdoc/require-param
function legacy(a, b) {}

Также возможно отключение отдельных тегов или контекстов через конфигурацию, что используется при работе с устаревшим кодом.

Стратегии применения в проекте

При внедрении eslint-plugin-jsdoc обычно выделяются несколько уровней строгости:

  • базовый уровень: проверка наличия описаний и выравнивания
  • средний уровень: контроль параметров и возвращаемых значений
  • строгий уровень: полная валидация API-контракта и типов

Такая градация позволяет адаптировать линтинг под размер и зрелость проекта без перегрузки разработчиков избыточными требованиями.

Оглавление