223 lines
4.4 KiB
Markdown
223 lines
4.4 KiB
Markdown
---
|
||
title: "「JavaScript」JSDoc 学习记录"
|
||
date: 2025-03-15T23:19:54Z
|
||
lastmod: 2025-03-15T23:25:49Z
|
||
tags: [JavaScript,Web 前端,学习,记录]
|
||
---
|
||
|
||
# 「JavaScript」JSDoc 学习记录
|
||
|
||
## 信息
|
||
|
||
### @deprecated
|
||
|
||
#### 简介
|
||
|
||
用于将函数、属性等内容标记为不推荐使用。
|
||
|
||
#### 参考
|
||
|
||
- [Use JSDoc: @deprecated](https://jsdoc.app/tags-deprecated.html)
|
||
- [TypeScript: Documentation](https://www.typescriptlang.org/docs/handbook/jsdoc-supported-types.html#deprecated)
|
||
|
||
### @description
|
||
|
||
#### 简介
|
||
|
||
用于给变量、函数等内容添加说明信息。
|
||
|
||
#### 语法
|
||
|
||
```plaintext
|
||
@description <说明内容>
|
||
@desc <说明内容>
|
||
```
|
||
|
||
#### 参考
|
||
|
||
- [Use JSDoc: @description](https://jsdoc.app/tags-description.html)
|
||
|
||
## 类型
|
||
|
||
### @callback
|
||
|
||
#### 简介
|
||
|
||
与 `@typedef` 类似，但它主要用于描述函数。
|
||
|
||
#### 语法
|
||
|
||
```javascript
|
||
/**
|
||
* @callback ExampleFunction
|
||
* @param {string} data
|
||
* @param {number} [index]
|
||
* @returns {boolean}
|
||
*/
|
||
```
|
||
|
||
#### 参考
|
||
|
||
- [Use JSDoc: @callback](https://jsdoc.app/tags-callback.html)
|
||
- [TypeScript: Documentation](https://www.typescriptlang.org/docs/handbook/jsdoc-supported-types.html#typedef-callback-and-param)
|
||
|
||
### @param
|
||
|
||
#### 简介
|
||
|
||
与 `@type` 类似，但它用于描述函数的参数类型。
|
||
|
||
#### 语法
|
||
|
||
```javascript
|
||
/**
|
||
* @param {Object} options
|
||
* @param {string} options.prop1
|
||
* @param {number} options.prop2
|
||
* @param {number} [options.prop3]
|
||
*/
|
||
function example(options) {
|
||
return options;
|
||
}
|
||
```
|
||
|
||
#### 参考
|
||
|
||
- [Use JSDoc: @param](https://jsdoc.app/tags-param.html)
|
||
- [TypeScript: Documentation](https://www.typescriptlang.org/docs/handbook/jsdoc-supported-types.html#typedef-callback-and-param)
|
||
|
||
### @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>> }
|
||
*/
|
||
```
|
||
|
||
#### 参考
|
||
|
||
- [TypeScript: Documentation](https://www.typescriptlang.org/docs/handbook/jsdoc-supported-types.html#template)
|
||
|
||
### @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 }
|
||
```
|
||
|
||
#### 参考
|
||
|
||
- [Use JSDoc: @type](https://jsdoc.app/tags-type.html)
|
||
- [TypeScript: Documentation](https://www.typescriptlang.org/docs/handbook/jsdoc-supported-types.html#type)
|
||
|
||
### @typedef
|
||
|
||
#### 简介
|
||
|
||
用于描述一个自定义的类型。
|
||
|
||
#### 语法
|
||
|
||
```javascript
|
||
/**
|
||
* @typedef {object} ExampleType - 定义一个名称为 ExampleType 的类型
|
||
* @property {string} prop1 - 一个 string 类型的属性
|
||
* @property {number} prop2 - 一个 number 类型的属性
|
||
* @property {number} [prop3] - 一个 number 类型的可选属性
|
||
*/
|
||
```
|
||
|
||
#### 参考
|
||
|
||
- [Use JSDoc: @typedef](https://jsdoc.app/tags-typedef.html)
|
||
- [TypeScript: Documentation](https://www.typescriptlang.org/docs/handbook/jsdoc-supported-types.html#typedef-callback-and-param)
|
||
|
||
|