docs: 添加文章内容（2013 ~ 2023）

docs/content/jsdoc-learning.md

@@ -0,0 +1,222 @@
+---
+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)
+
+‍