JSDoc 3 是一个用于 JavaScript 的API文档生成器，类似于 Javadoc 或 phpDocumentor。可以将文档注释直接添加到源代码中。JSDoc 工具将扫描您的源代码并为您生成一个 HTML 文档网站。
每个注释必须以 /** 序列开头
常用标签
- @type 用于表示类型
- @typedef 用于表示接口和自定义类型
- @property 用于表示类、命名空间或其他对象的属性
- @enum 用于表示枚举
- @param 用于标记函数参数的名称、类型和描述。
- @returns 用于标记函数返回值
- @template 用于标识泛型
类型声明
基础类型
/** @type {boolean} */
let isDone = false; // 布尔
/** @type {number} */
let decLiteral = 6; // 数字
/** @type {string} */
let myname = "bob"; // 字符串
/** @type {undefined} */
let u = undefined; // undefined
/** @type {null} */
let n = null; // null
数组和元组
/** @type {number[]} */
let list = [1, 2, 3]; // 数组
/** @type {[string, number]} */
let tuple = ['abc', 10] // 元组
对象和接口
/** @type {{ name: string; age: number }} */
const person = { name: 'zs', age: 100 };
// 定义 Person 的接口
/**
* @typedef {object} Person
* @property {string} name 姓名
* @property {number} age 年龄
*/
/** @type {Person} */
const person = { name: 'zs', age: 100 };
函数
/**
* @param {object} data 参数
* @param {string} data.name 姓名
* @param {number} [data.age] 年龄
* @returns {void}
*/
function fn(data) {}
/**
* @param {{ name: string; age?: number }} data 参数
* @returns {void}
*/
function fn(data) {}
可选属性 []
/**
* @typedef {object} Person
* @property {string} name 姓名
* @property {number} [age] 年龄
*/
/** @type {Person} */
const person = { name: 'zs' };
索引签名
/** @type {Object<string, object>} */
/** @type {{[key: string]: any}} */
keyof
/**
* @typedef {object} Person
* @property {string} name 姓名
* @property {number} age 年龄
*/
/** @type {keyof Person} */
let key = 'name';
枚举类型
/** @enum {string} */
const Color = {
Red: 'red',
Green: 'green',
Blue: 'blue',
};
/** @type {Color} */
let color = Color.Red;
字面量类型
/**
* @typedef {'red' | 'green' | 'blue'} Color 颜色取值
*/
/** @type {Color} */
let color = 'red';
联合类型
/** @type {string | number} */
let value = 'a';
实用高级类型
Readonly
/**
* @typedef {object} Person
* @property {string} name 姓名
* @property {number} age 年龄
*/
/** @type {Readonly<Person>} */
const person = { name: 'zs', age: 100 }
Partial
/**
* @typedef {object} Person
* @property {string} name 姓名
* @property {number} age 年龄
*/
/** @type {Partial<Person>} */
const person = {}
Record
/** @type {Record<'a' | 'b', number>} */
const obj = { a: 1, b: 2 }
Pick
/**
* @typedef {object} Person
* @property {string} name 姓名
* @property {number} age 年龄
*/
/** @type {Pick<Person, 'name'>} */
const person = { name: 'zs' }
Omit
/**
* @typedef {object} Person
* @property {string} name 姓名
* @property {number} age 年龄
*/
/** @type {Omit<Person, 'age'>} */
const person = { name: 'zs' }
Extract
/** @typedef {'a' | 'b' | 'c'} A */
/** @typedef {'b' | 'c' | 'd'} B */
/** @type {Extract<A, B>} */ // 从 A 中选取 B 也有的
let value = 'b';
Exclude
/** @typedef {'a' | 'b' | 'c'} A */
/** @typedef {'b' | 'c' | 'd'} B */
/** @type {Exclude<A, B>} */ // 从 A 中去掉 B 也有的
let value = 'a';
泛型
/**
* @template T
* @param {T} arg 参数
* @returns {T}
*/
function identity(arg) {
return arg;
}
启用类型检查
VSCode 内置支持 JSDoc
方式一：项目根目录或需要检查的文件夹下创建 jsconfig.json 进行如下配置（code.visualstudio.com/docs/langua…）；
{
"compilerOptions": {
"checkJs": true
}
}
方式二：在 vscode 设置中搜索 checkJs 配置并启用；
