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.