JSDOC为JavaScript代码库提供了添加类型，并在注释中提供适当的约定，因此Visual Studio Code等不同的IDE可以识别定义的类型，显示并通过自动完成使编码更轻松。定义放在/** */注释中。
例子
可以使用@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, any>>} 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',
};
文档验证
linter可以验证文档。添加以下软件包并更新Linter配置文件。
npm i -D eslint-plugin-jsdoc
// .eslintrc.js
module.exports = {
extends: ['plugin:jsdoc/recommended'],
};
运行衬里，如果必须改进一些东西，它将显示警告。
生成文档
运行以下命令以递归生成文档，包括通往readme.md和package.json文件的路径，以便在生成的文档中包含内容。将跳过标有@private标签的符号。
npx jsdoc src -r --destination docs --readme ./README.md --package ./package.json
此命令可以包含在CI/CD管道中，这取决于项目的需求。