安装
npm install -g jsdoc
生成
jsdoc [path]
然后会生成 out 文件夹，打开 html 就可以看到了
配置检测 JS
{
"compilerOptions": {
"checkJs": true
}
}
注释
必须以两个星号开头才能被解析
标记函数
- 普通用法
/**
* 这是一个函数的注释
* @param {string} name 必选参数
* @param {number} [age=18] 可选参数带默认值
* @param {?number} age1 可选参数不带默认值
* @returns {Promise<boolean>} 这是函数的返回值
*/
- 函数重载
/**
* @overload
* @param {string} value
* @return {void}
*/
/**
* @overload
* @param {number} value
* @param {number} [maximumFractionDigits]
* @return {void}
*/
/**
* @param {string | number} value
* @param {number} [maximumFractionDigits]
*/
- 使用对象进行标记
/**
* @function
* @param {number} a
* @param {number} b
*/
const sum = (a, b) => {}
- 使用对象标记重载
/**
* @type {{
* (ticket: string, userid: string): void;
* (ticket: number, firstname: string, lastname: string): void;
* }}
*/
const assignSlave = (ticket, userid, lastname = "") => {}
定义类型
- 定义对象类型
/**
* @typedef {{ name: string, age: number }} Person
*/
/**
* User type definition
* @typedef {Object} User
* @property {string} email
* @property {string} [nickName]
*/
- 定义函数类型
/**
* @callback requestCallback
* @param {number} responseCode
* @param {string} responseMessage
*/
泛型
- 使用
@template
/**
* @template {Array} [T=number[]]
* @param {T} array
* @returns T['length']
*/
function t(array) {
return array.length
}
- 使用
typescript
/**
* @type {{<T extends Array = number[]>(array: T): T['length']}}
*/
function t1(array) {
return array.length
}
导入其他文件定义的类型
这个导入的可以是 @typedef 标记的，也可以是 .d.ts 文件的，甚至是其他 ts 文件中定义的
/**
* @type {import('./index').Person} person 从第三方模块导入
*/
类型体操
就和 ts 里面一样玩耍就可以了。
/**
* 搜索结果
* @type {Awaited<ReturnType<typeof queryCustomerOrShopList>>['list']}
*/
results: [],
其他类型
- 弃用
/**
* @deprecated since version 2.0
*/
function old() {}
