JSDoc 支持通过 @typedef 声明递归类型，可清晰描述如嵌套人员结构、树形列表等任意深度的嵌套对象，无需额外类定义，兼顾类型表达力与工具链兼容性。
jsdoc 支持通过 `@typedef` 声明递归类型，可清晰描述如嵌套人员结构、树形列表等任意深度的嵌套对象，无需额外类定义，兼顾类型表达力与工具链兼容性。
在 JavaScript 项目中（尤其是未使用 TypeScript 的场景），为递归结构（如树形数据、嵌套文档节点、带子项的人员对象）编写准确的 JSDoc 类型注解，是提升代码可维护性与 IDE 智能提示质量的关键。核心方法是利用 @typedef 显式声明自引用类型。
✅ 推荐写法：语义清晰、结构分明
/**
* @typedef Person
* @type {object}
* @property {string} firstName 名字（注意命名一致性，推荐 camelCase）
* @property {string} lastName 姓氏
* @property {Person[]} [children=[]] 可选的子节点数组，每个元素均为 Person 类型
*/
/**
* 处理嵌套人员结构的函数
* @param {Person} person - 根节点人员对象
*/
function processPerson(person) {
console.log(`${person.firstName} ${person.lastName}`);
if (Array.isArray(person.children)) {
person.children.forEach(processPerson);
}
}? 提示：
[children=[]]中的方括号表示该属性为可选（optional），等价于@property {Person[]} [children]；若需默认值语义，应在实现中处理，JSDoc 仅作类型与可选性标注。
✅ 简洁写法（适合简单结构）
若类型较轻量且上下文明确，也可采用内联 @typedef：
dmap-jsapi-skill
下载
DMap GL地图JSAPI（dmapgl）开发指南。用于编写、审查、调试 DMap 地图 API 代码，涵盖地图初始化、覆盖物渲染、图层管理、事件处理、控件交互等任务。当用户提及 dmap、dmapgl、jsapi‑gl 或相关地图开发需求时自动触发。
/**
* @typedef {{firstName: string, lastName: string, children: Person[]}} Person
*/
/**
* @param {Person} person
*/⚠️ 注意：此写法将类型定义压缩为一行，牺牲了属性说明能力（无法添加 @property 描述），不适用于需文档化字段含义或存在复杂嵌套/联合类型的场景。
⚠️ 重要注意事项
-
命名一致性：类型名（如
Person）需首字母大写，且在作用域内唯一；引用时直接使用{Person}，无需加引号或typeof。 -
工具链兼容性：主流编辑器（VS Code）、TypeScript（启用
allowJs+checkJs）、以及 JSDoc 工具链（如jsdoc3v3.6.7+）均支持该语法。但旧版工具可能忽略递归引用，建议保持 JSDoc 版本 ≥ 3.6.0。 -
避免循环引用陷阱：确保
@typedef声明位于所有引用它的 JSDoc 注释之前（通常置于文件顶部或模块导出前）。 -
与 TypeScript 协同：若项目未来迁移到 TS，此类
@typedef可平滑对应为interface Person { ... }，降低迁移成本。
通过合理运用 @typedef，你能在纯 JavaScript 环境中构建出具备强类型表达力、IDE 友好、且符合行业惯例的递归类型文档——无需引入类、无需牺牲简洁性，真正实现“写一次，处处受益”。
