JSDoc обеспечивает добавление типов в кодовую базу JavaScript с соответствующими соглашениями внутри комментариев, поэтому различные IDE, такие как Visual Studio Code, могут распознавать определенные типы, отображать их и упрощать кодирование с помощью автодополнения. Определения помещены внутри /** */ комментариев.

Примеры

Пользовательские типы можно определить с помощью тегов @typedef и @property. Каждое свойство имеет тип, и если свойство является необязательным, его имя помещается в квадратные скобки, а описание может быть включено после имени свойства. Глобальные типы должны быть определены в *.jsdoc.js файлах для использования в нескольких файлах без импорта. * представляет любой тип.

/**
 * @typedef {object} CollectionItem
 * @property {string} [collectionName] - collection name is optional string field
 * @property {boolean} isRevealed - reveal status
 * @property {number} floorPrice - floor price
 * @property {?string} username - username is a nullable field
 * @property {Array.<number>} prices - prices array
 * @property {Array.<string>} [buyers] - optional buyers array
 * @property {Array.<Object<string, *>>} data - some data
 */

Классы распознаются автоматически, поэтому теги @class и @constructor можно опустить.

/**
 * Scraper for websites
 */
class Scraper {
  /**
   * Create scraper
   * @param {string} url - website's URL
   */
  constructor(url) {
    this.url = url;
  }
  // ...
}

Комментарии, начинающиеся с описания, могут опускать тег @description. Параметры функций и типы возвращаемых функций могут быть определены с помощью тегов @param и @returns. Несколько типов возврата можно обрабатывать с помощью оператора |. Устаревшие части кодовой базы могут быть аннотированы тегом @deprecated.

/**
 * Gets prices list
 * @private
 * @param {Array.<number>} prices - prices array
 * @returns {string|undefined}
 */
const getPricesList = (prices) => {
  if (prices.length > 0) return prices.join(',');
};
/**
 * Get data from the API
 * @deprecated
 * @returns {Promise<CollectionItem>}
*/
const getData = async () => {
  // ...
};

Типы переменных можно документировать с помощью тегов @type, а константы могут использовать теги @const.

/**
 * Counter for the requests
 * @type {number}
 */
let counter;
/**
 * HTTP timeout in milliseconds
 * @const {number}
*/
const HTTP_TIMEOUT_MS = 3000;

Перечисления можно документировать с помощью тегов @enum и @readonly.

/**
 * Some states
 * @readonly
 * @enum {string}
 */
const state = {
  STARTED: 'STARTED',
  IN_PROGRESS: 'IN_PROGRESS',
  FINISHED: 'FINISHED',
};

Проверка документов

Линтер может проверить документы. Добавьте следующий пакет и обновите файл конфигурации линтера.

npm i -D eslint-plugin-jsdoc
// .eslintrc.js
module.exports = {
  extends: ['plugin:jsdoc/recommended'],
};

Запустите линтер, и он покажет предупреждения, если что-то нужно улучшить.

Создание обзора документов

Выполните следующую команду, чтобы рекурсивно сгенерировать HTML-файлы с обзором документации, включая содержимое README.md и package.json. Символы, отмеченные тегами @private, будут пропущены.

npx jsdoc src -r --destination docs --readme ./README.md --package ./package.json

В зависимости от потребностей проекта эту команду можно включить в конвейер CI/CD.