使用JSDoc可为JavaScript复杂对象提供类型提示。1. 用@param标注嵌套对象结构，如user.id、user.profile.email；2. 用@typedef定义可复用类型，如UserProfile和User；3. 支持数组、可选属性和联合类型，如User[]、string|null、[total]。通过JSDoc能提升代码可读性和IDE智能提示，适合大型项目协作。
在 JavaScript 中，虽然没有原生的“注解”（Annotation）机制像 Java 那样，但在使用 JSDoc 时，我们可以通过注释来为复杂对象结构添加类型说明，帮助开发者理解参数、返回值的结构，也能被 IDE 和 TypeScript 正确识别。
1. 使用 JSDoc 标注复杂对象参数
当函数接收一个包含多层嵌套的对象作为参数时，可以使用 @param 搭配对象结构描述来清晰定义其类型和字段：
/** * 更新用户信息 * @param {Object} user - 用户对象 * @param {string} user.id - 用户唯一ID * @param {string} user.name - 用户名 * @param {number} user.age - 年龄 * @param {Object} user.profile - 用户档案 * @param {string} user.profile.email - 邮箱地址 * @param {boolean} user.profile.isActive - 是否激活 */ function updateUser(user) { // ... }这样写后，调用该函数时，IDE 就能提示 user 对象应有的结构。
2. 使用 typedef 定义可复用的复杂类型
如果某个复杂对象会被多次使用，推荐用 @typedef 提前定义类型，提高可维护性：
/** * @typedef {Object} UserProfile * @property {string} email - 用户邮箱 * @property {boolean} isActive - 账户是否激活 * @property {string} [avatar] - 头像URL（可选） *//**
- @typedef {Object} User
- @property {string} id
- @property {string} name
- @property {number} age
- @property {UserProfile} profile */
/**
- @param {User} user - 完整用户对象 */ function saveUser(user) { // ... }
使用 @typedef 后，多个函数都可以引用相同的类型定义，结构更清晰。
3. 标注数组、可选属性与联合类型
JSDoc 还支持更复杂的类型表达，比如数组、可选字段、联合类型等：
/** * @typedef {Object} ApiResponse * @property {boolean} success * @property {string | null} message - 可为字符串或 null * @property {User[]} data - 用户对象数组 * @property {number} [total] - 总数（可选） */-
?表示可选：如
@property {number} [total] -
| 表示联合类型：如
string | null -
[] 表示数组：如
User[]
4. 标注函数返回的复杂对象
使用 @returns 或 @return 来说明返回值结构：
/** * 获取当前用户信息 * @returns {User} 返回用户对象 */ function getCurrentUser() { return fetch('/api/user').then(res => res.json()); }也可以直接内联描述返回结构：
/** * @returns {Object} * @property {string} token - 认证令牌 * @property {number} expires - 过期时间戳 */基本上就这些。通过合理使用 JSDoc 的注解方式，即使在纯 JS 中也能实现接近 TypeScript 的类型提示体验，尤其适合大型项目或团队协作。
