「JavaScript」JSDoc 学习记录
信息
@deprecated
简介
用于将函数、属性等内容标记为不推荐使用。
参考
@description
简介
用于给变量、函数等内容添加说明信息。
语法
plaintext
@description <说明内容>
@desc <说明内容>参考
类型
@callback
简介
与 @typedef 类似，但它主要用于描述函数。
语法
javascript
/**
* @callback ExampleFunction
* @param {string} data
* @param {number} [index]
* @returns {boolean}
*/参考
@param
简介
与 @type 类似，但它用于描述函数的参数类型。
语法
javascript
/**
* @param {Object} options
* @param {string} options.prop1
* @param {number} options.prop2
* @param {number} [options.prop3]
*/
function example(options) {
return options;
}参考
@template
示例
javascript
/**
* @interface
* @template TData
* @typedef {object} ResObject
* @property {number} code
* @property {TData} data
* @property {string} message
* @property {boolean} success
*/
/**
* @interface
* @template TData
* @typedef ResPromise
* @type { import('axios').AxiosPromise<ResObject<TData>> }
*/参考
@type
简介
用于描述对象的类型。
语法
plaintext
@type {类型名称}类型名称（名称表达式）
指定一个类型名称。
plaintext
{boolean}
{number}
{string}
{HTMLElement}
{myNamespace.MyClass}多个类型
使用括号包括，使用
|分隔多个类型。
表示值可能是几种类型中的一种。
plaintext
{(boolean|number)}数组和对象
JSDoc 支持 Closure Compiler 语法定义的数组和对象类型。
可以在类型名称的后方添加[] 描述数组项的类型。例如string[]表示字符串数组。
对于具有已知的属性的对象，可以使用 Closure Compiler 语法描述类型。可以分别描述每个属性，以便为每个属性指定更详细的信息。
一个保存 MyClass 实例对象的数组：
plaintext
{Array.<MyClass>}
{MyClass[]}一个 key 类型为 string，值类型为 number 的对象：
plaintext
{Object.<string, number>}一个类数组对象：
plaintext
{Object.<number, object>}一个名称为 myObj，包含属性 a（number）和 b（任意类型）的对象：
plaintext
{{a: number, b: string, c}} myObj
{Object} myObj
{number} myObj.a
{*} myObj.b导入类型
可以使用
import导入其他文件中的类型。
注意：此语法是特定于 TypeScript 的，不同于 JSDoc 标准。
从文件 types.js 中导入 Example 类型
plaintext
{ import("./types").Example }参考
@typedef
简介
用于描述一个自定义的类型。
语法
javascript
/**
* @typedef {object} ExampleType - 定义一个名称为 ExampleType 的类型
* @property {string} prop1 - 一个 string 类型的属性
* @property {number} prop2 - 一个 number 类型的属性
* @property {number} [prop3] - 一个 number 类型的可选属性
*/参考