jsdoc 配合 vs code 可实现类 typescript 的类型提示：需规范书写 @param、@returns、@type 等标签，为对象、api 响应等显式标注类型，并结合 eslint-plugin-jsdoc 强制校验。

直接用 JSDoc 配合现代 IDE（如 VS Code），就能在纯 JavaScript 项目里获得接近 TypeScript 的类型提示和错误预警，无需改后缀、不加编译步骤，轻量但效果实在。

写对格式：JSDoc 注释要规范

JSDoc 不是随便写个注释就行，得按标准结构来，IDE 才能准确提取信息。核心是用 /** ... */ 包裹，里面用 @param、@returns、@type 等标签明确声明。

• @param 后跟参数名和花括号里的类型，支持可选（加 [ ]）和默认值说明
• @returns 明确函数返回值类型，比如 {Promise}
• @type 可直接标注变量或属性类型，适合复杂对象或第三方库返回值

补全关键类型：让 IDE 看懂你的数据结构

光写函数签名不够，JS 对象、API 响应、配置项这些“隐性结构”最容易出错。用 JSDoc 把它们显式标出来：

Wjs Uploading Video

将一个或多个视频上传至YouTube。当用户想“上传到YouTube”“发YouTube”“批量上传”“upload to YouTube”“post videos to YouTube”或发布到YouTube时使用此技能。

下载

• 给对象字面量加 @type，例如：/** @type {{id: number, name: string, active?: boolean}} */ const user = {...}
• 为 API 调用结果标注类型，配合 fetch 或 axios 使用时特别有用
• 导出的常量或配置对象也值得加注释，避免别处误用字段

利用 IDE 内置能力：VS Code 就够用

VS Code 默认启用 TypeScript 语言服务，它会自动解析 JSDoc 并提供智能提示，不需要额外插件。

• 输入点号（.）时，能列出对象所有已知属性，并标出哪些是可选的
• 调用函数时，悬浮显示参数类型和文档描述，参数顺序错或类型不对会实时标红
• 重命名变量或函数时，支持跨文件安全重构（前提是类型信息足够清晰）

配合 ESLint 强化约束：防止文档和代码脱节

光靠自觉容易漏写或写错 JSDoc。引入 eslint-plugin-jsdoc 能把规范变成硬性要求：

• 开启 require-jsdoc，强制函数、类、导出成员必须有注释
• 启用 check-param-names，确保注释里的参数名和函数签名完全一致
• 使用 require-returns 和 require-description，避免空泛或缺失关键信息