Руководства

# Правила документирования кода на JavaScript

JSDoc - это стандартный способ документирования кода на JavaScript с помощью специальных комментариев, которые можно извлекать автоматически для создания документации. Вот основные правила введения комментариев JSDoc:

  1. Типы данных: Указывайте типы данных параметров функций и возвращаемого значения. Например:

    /**
 * Функция для сложения двух чисел.
 * @param {number} a - Первое число.
 * @param {number} b - Второе число.
 * @returns {number} Сумма двух чисел.
 */
function add(a, b) {
  return a + b;
}

  2. Описания: При необходимости добавляйте описание для функций, переменных или классов, чтобы пояснить их назначение или особенности. Описания заключаются в текстовые блоки, начинающиеся с символов /** и заканчивающихся /. Например:

    /**
 * Класс, представляющий пользователя.
 */
class User {
  // ...
}

  3. Опциональные параметры: Указывайте, если параметр функции является опциональным, добавляя к нему символ []. Например:

    /**
 * Функция для умножения двух чисел.
 * @param {number} a - Первое число.
 * @param {number} [b=1] - Второе число (опционально, по умолчанию 1).
 * @returns {number} Произведение двух чисел.
 */
function multiply(a, b = 1) {
  return a * b;
}

  4. Документирование классов и методов: Для классов и их методов также указывайте типы данных входных параметров и возвращаемых значений, а также описания класса и его методов.

    /**
 * Класс, представляющий книгу.
 */
class Book {
  /**
   * Создает новую книгу.
   * @param {string} title - Заголовок книги.
   * @param {string} author - Автор книги.
   */
  constructor(title, author) {
    // ...
  }

  /**
   * Получает информацию о книге.
   * @returns {string} Информация о книге в формате "Заголовок - Автор".
   */
  getInfo() {
    // ...
  }
}

  5. Использование ссылок: Если вы ссылаетесь на другие функции, классы или переменные в комментариях JSDoc, используйте ссылки для лучшей связи документации. Например:

    /**
 * Функция, которая возвращает случайное число.
 * @returns {number} Случайное число от 0 до 1.
 */
function getRandom() {
  // ...
}

  6. Использование маркеров: В JSDoc есть различные маркеры, которые позволяют указывать информацию, такую как @param, @returns, @throws, @deprecated, @private, и другие. Используйте соответствующие маркеры для правильного оформления документации.

  7. Документирование модулей и пространств имен: Если вы используете модули или пространства имен, документируйте их, чтобы обеспечить понимание их назначения и использования.

Описание маркеров JSDoc

  1. @param: Описывает параметры функции или метода.
    Пример:

    /**
 * Функция для сложения двух чисел.
 * @param {number} a - Первое число.
 * @param {number} b - Второе число.
 */
function add(a, b) {
  // ...
}

  2. @returns: Описывает возвращаемое значение функции или метода.
    Пример:

    /**
 * Функция для умножения двух чисел.
 * @param {number} a - Первое число.
 * @param {number} b - Второе число.
 * @returns {number} Произведение двух чисел.
 */
function multiply(a, b) {
  // ...
}

  3. @throws: Описывает исключения, которые может выбросить функция или метод.
    Пример:

    /**
 * Функция для деления двух чисел.
 * @param {number} dividend - Делимое.
 * @param {number} divisor - Делитель.
 * @returns {number} Частное двух чисел.
 * @throws {Error} Ошибка, если делитель равен 0.
 */
function divide(dividend, divisor) {
  if (divisor === 0) {
    throw new Error("Деление на ноль недопустимо.");
  }
  // ...
}

  4. @deprecated: Указывает, что функция, метод, класс или переменная устарела и может быть удалена в будущих версиях. Рекомендуется использовать другой альтернативный подход.
    Пример:

    /**
 * Функция для вычисления квадрата числа (устаревшая, используйте функцию `calculateSquare`).
 * @deprecated
 * @param {number} x - Число, для которого нужно вычислить квадрат.
 * @returns {number} Квадрат числа.
 */
function square(x) {
  return x * x;
}

  5. @private: Указывает, что функция, метод или переменная являются приватными и предназначены только для внутреннего использования внутри модуля, класса или объекта. Не следует использовать их вне данного контекста.
    Пример:

    /**
 * Класс, представляющий пользователя.
 * @class
 * @private
 */
class User {
  // ...
}

  6. @typedef: Позволяет создавать свои пользовательские типы данных (алиасы) для улучшения понимания кода.
    Пример:

    /**
 * @typedef {Object} User
 * @property {string} name - Имя пользователя.
 * @property {number} age - Возраст пользователя.
 */

  7. @enum: Описывает перечисление (enum) - набор именованных константных значений.
    Пример:

    /**
 * @enum {string}
 * @property {string} RED - Красный цвет.
 * @property {string} GREEN - Зеленый цвет.
 * @property {string} BLUE - Синий цвет.
 */
const Colors = {
  RED: 'red',
  GREEN: 'green',
  BLUE: 'blue'
};

  8. @namespace: Позволяет описывать пространства имен для группировки связанных функций, классов и переменных.
    Пример:

    /**
 * Пространство имен для работы с математическими операциями.
 * @namespace
 */
const MathUtils = {
  // ...
};

  9. @callback: Описывает тип функции обратного вызова (callback).
    Пример:

    /**
 * Функция, выполняющая операцию над числами.
 * @callback MathOperation
 * @param {number} a - Первое число.
 * @param {number} b - Второе число.
 * @returns {number} Результат операции.
 */

  10. @class: Описывает конструктор класса и его свойства/методы.
    Пример:

    /**
 * Класс, представляющий книгу.
 * @class
 */
class Book {
  /**
   * Создает новую книгу.
   * @constructor
   * @param {string} title - Заголовок книги.
   * @param {string} author - Автор книги.
   */
  constructor(title, author) {
    // ...
  }

  /**
   * Получает информацию о книге.
   * @returns {string} Информация о книге в формате "Заголовок - Автор".
   */
  getInfo() {
    // ...
  }
}

  11. @readonly: Помечает свойство объекта как доступное только для чтения (read-only).
    Пример:

    /**
 * Объект с информацией о книге.
 * @readonly
 * @type {object}
 * @property {string} title - Заголовок книги.
 * @property {string} author - Автор книги.
 */
const bookInfo = {
  title: "Название книги",
  author: "Имя автора"
};

  12. @example: Предоставляет пример использования функции, класса или метода.
    Пример:

    /**
 * Функция для сложения двух чисел.
 * @param {number} a - Первое число.
 * @param {number} b - Второе число.
 * @returns {number} Сумма двух чисел.
 * @example
 * // Пример использования:
 * const result = add(5, 3);
 * // Результат: 8
 */
function add(a, b) {
  return a + b;
}

  13. @inheritdoc: Указывает, что документацию для данного элемента следует взять из другого места (родительского класса или метода).
    Пример:

    /**
 * Класс, представляющий книгу.
 * @class
 */
class Book {
  /**
   * Получает информацию о книге.
   * @returns {string} Информация о книге в формате "Заголовок - Автор".
   */
  getInfo() {
    // ...
  }
}

/**
 * Класс, представляющий электронную книгу.
 * @class
 * @extends Book
 */
class EBook {
  /**
   * @inheritdoc
   */
  getInfo() {
    // ...
  }
}

  14. @link: Создает ссылку на связанный ресурс, например, на документацию или веб-страницу.
    Пример:

    /**
 * Функция для работы с массивами.
 * См. {@link <https://developer.mozilla.org/ru/docs/Web/JavaScript/Reference/Global_Objects/Array>}
 * @param {Array} arr - Входной массив.
 */
function processArray(arr) {
  // ...
}

  15. @augments (или @extends): Указывает на родительский класс, от которого наследуется данный класс.
    Пример:

/**
 * Класс, представляющий животное.
 * @class
 */
class Animal {
  // ...
}

/**
 * Класс, представляющий кошку.
 * @class
 * @augments Animal
 */
class Cat extends Animal {
  // ...
}
  1. @this: Указывает тип контекста this для метода или функции.
    Пример:
/**
 * Функция для умножения числа на коэффициент.
 * @param {number} coefficient - Коэффициент.
 * @this {number}
 */
function multiplyByCoefficient(coefficient) {
  return this * coefficient;
}
  1. @typedef: Создает пользовательский тип данных (алиас) для повторного использования.
    Пример:
/**
 * @typedef {Object} Book
 * @property {string} title - Заголовок книги.
 * @property {string} author - Автор книги.
 */
  1. @template (или @generic): Описывает параметры шаблона для обобщенных типов (generic) в классах или функциях.
    Пример:
/**
 * Класс для хранения пары значений.
 * @template T, U
 */
class Pair {
  // ...
}
  1. @borrows: Позволяет "заимствовать" документацию из другого объекта или функции.
    Пример:
/**
 * @borrows SomeClass#someMethod as myMethod
 */
  1. @inheritdoc (или @override): Указывает, что данный метод или свойство наследует документацию из базового класса, но может быть переопределено.
    Пример:
/**
 * Базовый класс для всех фигур.
 * @class
 */
class Shape {
  /**
   * Вычисляет площадь фигуры.
   * @returns {number} Площадь.
   */
  calculateArea() {
    // ...
  }
}

/**
 * Класс, представляющий квадрат.
 * @class
 * @extends Shape
 */
class Square extends Shape {
  /**
   * @inheritdoc
   */
  calculateArea() {
    // ... Переопределение логики для квадрата ...
  }
}
  1. @record: Описывает структуру данных (запись), которая используется для представления простых объектов без методов.
    Пример:
/**
 * @record
 * @typedef {Object} Person
 * @property {string} name - Имя человека.
 * @property {number} age - Возраст человека.
 */
  1. @global: Описывает переменные или свойства, которые доступны в глобальной области видимости.
    Пример:
/**
 * Глобальная переменная, содержащая настройки приложения.
 * @global
 * @type {object}
 */
var appConfig = {
  // ...
};

← Соглашение о commit →