doc: update docs/typescript.md

docs/typescript.md

@@ -1634,6 +1634,248 @@ declare namespace MyClass {
 ```
 <!--rehype:className=wrap-text-->
 
+JSDoc 参考
+---
+
+### @type
+<!--rehype:wrap-class=row-span-2-->
+
+```javascript
+/** @type {string} */
+var s;
+/** @type {Window} */
+var win;
+/** @type {PromiseLike<string>} */
+var promisedString;
+// 您可以指定具有 DOM 属性的 HTML 元素
+/** @type {HTMLElement} */
+var elm = document.querySelector(selector);
+elm.dataset.myData = "";
+/** @type {number[]} */
+var ns;
+/** @type {Array.<number>} */
+var jsdoc;
+/** @type {Array<number>} */
+var nas;
+/** @type {string | boolean} */
+var sb;
+/** @type {{ a: string, b: number }} */
+var var9;
+/**
+ * 将任意“字符串”属性映射到“数字”的类地图对象
+ * @type {Object.<string, number>}
+ */
+var stringToNumber;
+/** @type {Object.<number, object>} */
+var arrayLike;
+/** @type {function(string, boolean): number} Closure syntax */
+var sbn;
+/** @type {(s: string, b: boolean) => number} TypeScript syntax */
+var sbn2;
+/** @type {Function} */
+var fn7;
+/** @type {function} */
+var fn6;
+/**
+ * @type {*} - can be 'any' type
+ */
+var star;
+/**
+ * @type {?} - unknown type (same as 'any')
+ */
+var question;
+/** @type {number | string} */
+var numberOrString = Math.random() < 0.5 ? "hello" : 100;
+var typeAssertedNumber = /** @type {number} */ (numberOrString);
+let one = /** @type {const} */(1);
+```
+
+### 导入类型
+
+```javascript
+// @filename: types.d.ts
+export type Pet = {
+  name: string,
+};
+// @filename: main.js
+/** @param { import("./types").Pet } p */
+function walk(p) {
+  console.log(`Walking ${p.name}...`);
+}
+```
+
+导入类型可以在类型别名声明中使用
+
+```javascript
+/**
+ * @typedef {import("./types").Pet} Pet
+ */
+/** @type {Pet} */
+var myPet;
+myPet.name;
+```
+
+如果您不知道类型，或者如果它有一个很烦人的大类型，`import types` 可以用来从模块中获取值的类型：
+
+```javascript
+/**
+ * @type {typeof import("./accounts").userAccount}
+ */
+var x = require("./accounts").userAccount;
+```
+
+### @param 和 @returns
+
+```javascript
+/**
+ * @param {string}  p1 - 一个字符串参数
+ * @param {string=} p2 - 可选参数（Google Closure 语法）
+ * @param {string} [p3] - 另一个可选参数（JSDoc 语法）
+ * @param {string} [p4="test"] - 具有默认值的可选参数
+ * @returns {string} 这是结果
+ */
+function stringsStrings(p1, p2, p3, p4) {
+  // TODO
+}
+```
+
+同样，对于函数的返回类型：
+
+```javascript
+/**
+ * @return {PromiseLike<string>}
+ */
+function ps() {}
+ 
+/**
+ * @returns {{ a: string, b: number }} - 可以使用“@returns”和“@return”
+ */
+function ab() {}
+```
+
+### @typedef, @callback, 和 @param
+<!--rehype:wrap-class=col-span-2 row-span-2-->
+
+```javascript
+/**
+ * @typedef {Object} SpecialType - 创建一个名为“SpecialType”的新类型
+ * @property {string} prop1 - SpecialType 的字符串属性
+ * @property {number} prop2 - SpecialType 的数字属性
+ * @property {number=} prop3 - SpecialType 的可选数字属性
+ * @prop {number} [prop4] - SpecialType 的可选数字属性
+ * @prop {number} [prop5=42] - 具有默认值的 SpecialType 的可选数字属性
+ */
+ 
+/** @type {SpecialType} */
+var specialTypeObject;
+specialTypeObject.prop3;
+```
+
+您可以在第一行使用 object 或 Object
+
+```javascript
+/**
+ * @typedef {object} SpecialType1 - 创建一个名为“SpecialType”的新类型
+ * @property {string} prop1 - SpecialType 的字符串属性
+ * @property {number} prop2 - SpecialType 的数字属性
+ * @property {number=} prop3 - SpecialType 的可选数字属性
+ */
+ 
+/** @type {SpecialType1} */
+var specialTypeObject1;
+```
+
+**@param** 允许对一次性类型规范使用类似的语法。 请注意，嵌套的属性名称必须以参数名称为前缀：
+
+```javascript
+/**
+ * @param {Object} options - 形状和上面的SpecialType一样
+ * @param {string} options.prop1
+ * @param {number} options.prop2
+ * @param {number=} options.prop3
+ * @param {number} [options.prop4]
+ * @param {number} [options.prop5=42]
+ */
+function special(options) {
+  return (options.prop4 || 1001) + options.prop5;
+}
+```
+
+**@callback** 类似于 **@typedef**，但它指定的是函数类型而不是对象类型：
+
+```javascript
+/**
+ * @callback Predicate
+ * @param {string} data
+ * @param {number} [index]
+ * @returns {boolean}
+ */
+ 
+/** @type {Predicate} */
+const ok = (s) => !(s.length % 2);
+```
+
+当然，这些类型中的任何一种都可以在单行 **@typedef** 中使用 TypeScript 语法声明：
+
+```javascript
+/** @typedef {{ prop1: string, prop2: string, prop3?: number }} SpecialType */
+/** @typedef {(data: string, index?: number) => boolean} Predicate */
+```
+
+### @template
+
+您可以使用 **@template** 标记声明类型参数。 这使您可以创建通用的函数、类或类型：
+
+```javascript
+/**
+ * @template T
+ * @param {T} x - 流向返回类型的通用参数
+ * @returns {T}
+ */
+function id(x) {
+  return x;
+}
+ 
+const a = id("string");
+const b = id(123);
+const c = id({});
+```
+
+使用逗号或多个标签来声明多个类型参数：
+
+```javascript
+/**
+ * @template T,U,V
+ * @template W,X
+ */
+```
+
+您还可以在类型参数名称之前指定类型约束。 只有列表中的第一个类型参数受到约束：
+
+```javascript
+/**
+ * @template {string} K - K 必须是字符串或字符串文字
+ * @template {{ serious(): string }} Seriousalizable - 一定要有 serious 的方法
+ * @param {K} key
+ * @param {Seriousalizable} object
+ */
+function seriousalize(key, object) {
+  // ????
+}
+```
+
+最后，您可以为类型参数指定默认值：
+
+```javascript
+/** @template [T=object] */
+class Cache {
+  /** @param {T} initial */
+  constructor(T) {
+  }
+}
+let c = new Cache()
+```
+
 CLI
 ---