「JavaScript」JSDoc 学习记录

信息

@description

简介

用于给变量、函数等内容添加说明信息。

语法

@description <说明内容>
@desc <说明内容>

参考

• Use JSDoc: @description

@deprecated

简介

用于将函数、属性等内容标记为不推荐使用。

参考

• Use JSDoc: @deprecated
• TypeScript: Documentation

类型

@type

简介

用于描述对象的类型。

语法

@type {类型名称}

类型名称（名称表达式）

指定一个类型名称。

{boolean}
{number}
{string}
{HTMLElement}
{myNamespace.MyClass}

多个类型

使用括号包括，使用 | 分隔多个类型。
表示值可能是几种类型中的一种。

{(boolean|number)}

数组和对象

JSDoc 支持 Closure Compiler 语法定义的数组和对象类型。
可以在类型名称的后方添加 [] 描述数组项的类型。例如 string[] 表示字符串数组。
对于具有已知的属性的对象，可以使用 Closure Compiler 语法描述类型。可以分别描述每个属性，以便为每个属性指定更详细的信息。

一个保存 MyClass 实例对象的数组：

{Array.<MyClass>}
{MyClass[]}

一个 key 类型为 string，值类型为 number 的对象：

{Object.<string, number>}

一个类数组对象：

{Object.<number, object>}

一个名称为 myObj，包含属性 a（number）和 b（任意类型）的对象：

{{a: number, b: string, c}} myObj

{Object} myObj
{number} myObj.a
{*} myObj.b

导入类型

可以使用 import 导入其他文件中的类型。
注意：此语法是特定于 TypeScript 的，不同于 JSDoc 标准。

从文件 types.js 中导入 Example 类型

{ import("./types").Example }

参考

• Use JSDoc: @type
• TypeScript: Documentation

@typedef

简介

用于描述一个自定义的类型。

语法

/**
 * @typedef {object} ExampleType - 定义一个名称为 ExampleType 的类型
 * @property {string} prop1 - 一个 string 类型的属性
 * @property {number} prop2 - 一个 number 类型的属性
 * @property {number} [prop3] - 一个 number 类型的可选属性
 */

参考

• Use JSDoc: @typedef
• TypeScript: Documentation

@callback

简介

与 @typedef 类似，但它主要用于描述函数。

语法

/**
 * @callback ExampleFunction
 * @param {string} data
 * @param {number} [index]
 * @returns {boolean}
 */

参考

• Use JSDoc: @callback
• TypeScript: Documentation

@param

简介

与 @type 类似，但它用于描述函数的参数类型。

语法

/**
 * @param {Object} options
 * @param {string} options.prop1
 * @param {number} options.prop2
 * @param {number} [options.prop3]
 */
function example(options) {
  return options;
}

参考

• Use JSDoc: @param
• TypeScript: Documentation

隐私政策和规则
点击此处查看详情
转载说明
欢迎任何网络媒体和网站转载本站的内容，转载时请注明作者和博客文章链接。
其他说明
本站部分内容可能已过时，仅供参考，请留意内容发布日期。