JsDocs

中文官网

大小写规则

在 JSDoc 中，数据类型的大小写规则遵循 JavaScript 和 TypeScript 的原始类型与对象类型的区分原则，具体规则如下

  1. 原始类型全小写，如：string, number, boolean, null, undefined
/**
 * @param {string}  // 字符串原始值（如 'hello'）
 * @param {number}  // 数字原始值（如 42）
 * @param {boolean} // 布尔原始值（如 true/false）
 * @param {symbol}  // Symbol 类型
 * @param {undefined}
 * @param {null}
 */
  1. 内置构造函数或类名首字母大写，如：Object, Array, Function, Date, RegExp

当引用 JavaScript 内置的构造函数（如 Object、Array、Date）或自定义的类/接口时，​​ 首字母需大写 ​​。例如：

/**
 * @param {Object} config - 配置对象（表示 Object 类型）
 * @param {Array<string>} list - 字符串数组
 * @typedef {Object} User - 自定义类型（接口）[1,6](@ref)
 *
 * @param {String}  // String 对象（如 new String('hello')）
 * @param {Number}  // Number 对象（如 new Number(42)）
 * @param {Object}  // 普通对象（如 {} 或 new Object()）
 * @param {Array}   // 数组（如 [] 或 new Array()）
 * @param {Date}    // 日期对象
 * @param {Function} // 函数
 * @param {RegExp}  // 正则表达式
 */
  1. 特殊情况：联合类型与 TypeScript 兼容 ​
  • Array 和泛型：如果数组元素是特定类型，需使用泛型语法 Array<Type> 或 Type[]：

在联合类型或复杂类型中，需保持与 TypeScript 类型系统的一致性。例如

/**
 * @param {string | number} id - 联合类型
 * @returns {Promise<boolean>} - 泛型类型
 * @param {Array<string>}  // 字符串数组
 * @param {number[]}       // 数字数组
 */
  • Object 与键值类型：若需指定对象的键值类型，使用 Object<string, number>：
/**
 * @param {Object<string, number>}  // 键为字符串，值为数字的对象
 */
  • any 和 void：any 表示任意类型，void 表示无返回值：
/**
 * @returns {void}  // 函数没有返回值
 * @param {any}     // 任意类型参数
 */
  1. 为什么需要区分大小写？

  • 语义明确：{string} 明确表示原始字符串，而 {String} 表示字符串对象。

  • 类型检查工具：如 TypeScript 或 IDE 会根据大小写推断类型，避免混淆。

  • 代码规范：统一风格提升可读性。

示例对比

/**
 * @param {string} name 参数是原始字符串
 * @param {String} nameObj 参数是 String 对象（极少使用）
 * @param {Object} options 参数是普通对象
 * @param {Object<string, number>} scores 参数是键为字符串、值为数字的对象
 */

总结

类型JSDoc写法示例值
原始类型string小写'hello'
对象类型String大写new String()
泛型Array<string>大写['hello', 'world']
键值类型Object<string, number>大写{name: 123, age: 23}
anyany小写any
voidvoid小写void
类型JSDoc写法原因
原始类型string、number小写避免与构造函数混淆（如 String vs string）
内置对象类型Object、Array大写表示 JavaScript 内置对象或类
自定义类型User、Book大写通过 @typedef 定义的类型或接口
泛型Array<string>大小写混合遵循构造函数大写，泛型参数小写（如 Array 是类，string 是原始类型）

遵循这一规则，代码的 JSDoc 会更加清晰准确！

最后编辑: