JSDoc 在 IDE 中实时提示处理

工具库 |

要让 VS Code 能实时提示 JSDoc 代码的编写错误或不规范的地方，可以通过结合 TypeScript 的类型检查功能和 ESLint 的 JSDoc 插件来实现。这种方法能够同时检测类型相关的错误和 JSDoc 的语法或规范问题，并在你编写代码时提供即时反馈。下面是具体的实现步骤：

步骤 1：启用 TypeScript 的类型检查

VS Code 内置了对 JavaScript 的支持，并可以通过 TypeScript 来检查 JSDoc 注释中的类型信息。这样可以实时发现 JSDoc 中类型与实际代码不匹配的问题。

方法 1：项目级类型检查

  1. 在项目根目录下创建一个 jsconfig.json 文件（如果还没有）。
  2. 添加以下配置以启用所有 JavaScript 文件的类型检查：
{
  "compilerOptions": {
    "checkJs": true
  },
  "include": ["src/**/*"]
}
  • 将 "src/**/*" 替换为你的 JavaScript 文件所在的实际路径。
  1. 保存文件后，VS Code 会自动开始检查 JSDoc 中的类型错误。

方法 2：单个文件类型检查

  1. 在需要检查的 JavaScript 文件顶部添加以下注释：
// @ts-check
  1. 保存文件后，VS Code 会对该文件启用类型检查。

效果：
启用类型检查后，如果 JSDoc 注释中的类型与实际代码不符（例如，函数声明返回 string 类型但实际返回 number），VS Code 会实时显示错误提示。

步骤 2：配置 ESLint 和 JSDoc 插件

ESLint 是一个强大的 linting 工具，通过添加 eslint-plugin-jsdoc 插件，可以专门检查 JSDoc 注释的语法和规范问题，例如参数名称错误、标签使用不当或缺少描述等。

安装 ESLint 和 JSDoc 插件

  1. 打开终端，进入你的项目目录。
  2. 如果项目中还没有安装 ESLint，运行以下命令安装：
npm install eslint --save-dev
  1. 安装 JSDoc 插件：
npm install eslint-plugin-jsdoc --save-dev

配置 ESLint

  1. 在项目根目录下创建或编辑 .eslintrc.json 文件。
  2. 添加以下内容以启用 JSDoc 插件并设置相关规则：
{
  "plugins": ["jsdoc"],
  "rules": {
    "jsdoc/check-param-names": "warn", // 检查参数名称是否匹配
    "jsdoc/check-tag-names": "warn", // 检查 JSDoc 标签是否有效
    "jsdoc/check-types": "warn" // 检查类型定义是否正确
    // 可根据需要添加其他规则
  }
}
  • 你可以访问 eslint-plugin-jsdoc 文档 查看更多可用规则，并根据项目需求调整规则的严格程度（"warn"、"error" 或 "off"）。

安装 VS Code 的 ESLint 扩展

  1. 打开 VS Code，按 Ctrl+Shift+X（或 Cmd+Shift+X）进入扩展视图。
  2. 搜索 "ESLint"，安装由 Microsoft 提供的官方 ESLint 扩展。
  3. 安装完成后，VS Code 会根据你的 ESLint 配置实时提示 JSDoc 问题。

步骤 3：可选调整配置

  • 自定义 ESLint 规则：根据项目规范调整 .eslintrc.json 中的 JSDoc 规则。例如，要求所有函数必须有 JSDoc 注释，或强制参数描述。
  • 处理重叠提示：如果类型检查和 ESLint 同时报告类型相关问题，可能会有重复提示。你可以在 ESLint 配置中禁用部分规则（如 "jsdoc/check-types": "off"），以避免冲突。

工作原理

  • TypeScript 类型检查：通过 jsconfig.json 或 // @ts-check，VS Code 使用 TypeScript 检查 JSDoc 中的类型定义，确保类型安全。
  • ESLint + JSDoc 插件：ESLint 检查 JSDoc 的语法和规范，例如标签使用是否正确、参数是否匹配函数签名等。
  • 实时反馈：两者结合后，你在编写 JSDoc 时，VS Code 会立即高亮显示错误或不规范的地方。

示例

假设你有以下代码：

// @ts-check
/**
 * @param {string} name - 用户名
 * @returns {number} - 年龄
 */
function getAge(name) {
  return "20"; // 类型错误：应返回 number
}
  • 类型检查：VS Code 会提示 返回类型应为 number，但实际返回了 string。
  • ESLint：如果配置了 jsdoc/check-param-names，当 @param 名称与函数参数不匹配时也会提示。

注意事项

  • 如果你只关心 JSDoc 的语法和规范问题，可以只使用 ESLint 和 JSDoc 插件，跳过类型检查。
  • 如果项目较大，启用类型检查可能会影响性能，可以选择仅对部分文件使用 // @ts-check。
  • VS Code 自带 TypeScript 支持，无需额外安装 TypeScript。

通过以上步骤，你就可以在 VS Code 中实现 JSDoc 代码的实时错误提示和规范检查，提升代码质量和开发效率！