VSCode 怎样利用快捷键快速生成 API 文档注释 VSCode 快速生成 API 注释的快捷键创意技巧-VSCode-PHP中文网

VSCode 怎样利用快捷键快速生成 API 文档注释 VSCode 快速生成 API 注释的快捷键创意技巧

爱谁谁

发布： 2025-08-11 15:48:02

原创

782人浏览过

<ol><li>安装 document this 或 jsdoc generator 等 vscode 扩展以支持 api 文档注释生成；2. 配置扩展的快捷键和行为，如设置 triggeronenter 为 true 以在输入 /** 后回车自动生成注释模板，includetypes 为 true 以自动推断类型；3. 使用 @param、@returns、@throws 等标签完善注释内容，并可通过 documentthis.customtemplate 自定义注释模板以统一团队风格；4. 全局安装 jsdoc 工具（npm install -g jsdoc），并通过 jsdoc 命令结合配置文件 jsdoc.conf.json 生成 html 格式的 api 文档，其中可指定源文件路径、输出目录、模板主题等选项，最终通过浏览器查看生成的文档，从而提升代码可读性、可维护性和团队协作效率。</li></ol>

VSCode 怎样利用快捷键快速生成 API 文档注释 VSCode 快速生成 API 注释的快捷键创意技巧

VSCode 提供了多种快捷键和扩展，可以帮助你快速生成 API 文档注释，显著提升开发效率。关键在于配置合适的工具，并掌握对应的快捷操作。

掌握 VSCode 快速生成 API 文档注释的快捷键技巧，不仅能提高代码的可读性和可维护性，还能让你在团队协作中更加高效。下面是一些实用的方法：

如何配置 VSCode 以支持快速生成 API 文档注释？

首先，你需要安装一些必要的 VSCode 扩展。JSDoc 是一种流行的 JavaScript 文档生成工具，因此安装 JSDoc 相关的扩展是第一步。比较推荐的是

Document This

登录后复制

和

JSDoc Generator

登录后复制

。

Document This

登录后复制

可以根据你的代码自动生成 JSDoc 注释模板，而

JSDoc Generator

登录后复制

则提供更高级的配置选项。

安装完成后，你需要配置这些扩展。以

Document This

登录后复制

为例，它默认的快捷键是

Ctrl+Alt+D

登录后复制

(Windows/Linux) 或

Cmd+Opt+D

登录后复制

(macOS)。你也可以在 VSCode 的

settings.json

登录后复制

文件中自定义快捷键。例如，你可以添加以下配置：

{
  "documentThis.triggerOnEnter": true,
  "documentThis.includeTypes": true
}

登录后复制

triggerOnEnter

登录后复制

设置为

true

登录后复制

意味着你只需要在函数或变量定义上方输入

/**

登录后复制

并按下回车键，就可以自动生成 JSDoc 注释模板。

includeTypes

登录后复制

设置为

true

登录后复制

则会自动推断参数和返回值的类型。

Document This

登录后复制

扩展有哪些高级用法？

除了基本的注释生成，

Document This

登录后复制

还支持一些高级用法。例如，你可以使用

@param

登录后复制

、

@returns

登录后复制

、

@throws

登录后复制

等 JSDoc 标签来更详细地描述 API 的参数、返回值和可能抛出的异常。

假设你有这样一个函数：

/**
 * Adds two numbers together.
 * @param {number} a The first number.
 * @param {number} b The second number.
 * @returns {number} The sum of the two numbers.
 * @throws {Error} If either a or b is not a number.
 */
function add(a, b) {
  if (typeof a !== 'number' || typeof b !== 'number') {
    throw new Error('Both a and b must be numbers.');
  }
  return a + b;
}

登录后复制

Document This

登录后复制

可以帮助你快速生成这些标签。你只需要在函数定义上方输入

/**

登录后复制

并按下回车键，然后根据需要修改生成的注释模板即可。

文心快码

文心快码（Comate）是百度推出的一款AI辅助编程工具

查看详情

另外，

Document This

登录后复制

还支持自定义模板。你可以在 VSCode 的

settings.json

登录后复制

文件中配置

documentThis.customTemplate

登录后复制

选项，来定义你自己的注释模板。这对于保持团队代码风格的一致性非常有用。

如何使用 JSDoc 生成最终的 API 文档？

生成 JSDoc 注释只是第一步，最终你需要使用 JSDoc 工具来生成 HTML 格式的 API 文档。首先，你需要全局安装 JSDoc：

npm install -g jsdoc

登录后复制

安装完成后，你就可以在命令行中使用

jsdoc

登录后复制

命令来生成文档了。例如，你可以运行以下命令：

jsdoc your-javascript-file.js

登录后复制

这会在当前目录下生成一个

out

登录后复制

目录，其中包含了 HTML 格式的 API 文档。你可以打开

out/index.html

登录后复制

文件来查看生成的文档。

当然，你也可以配置 JSDoc 的配置文件

jsdoc.conf.json

登录后复制

来定制文档的生成过程。例如，你可以指定文档的标题、主题、以及需要包含的文件和目录。

一个简单的

jsdoc.conf.json

登录后复制

示例如下：

{
  "source": {
    "include": ["./src"],
    "includePattern": ".js$",
    "excludePattern": "(node_modules/|docs)"
  },
  "opts": {
    "destination": "./docs",
    "recurse": true,
    "template": "node_modules/jsdoc-template"
  },
  "plugins": ["plugins/markdown"],
  "templates": {
    "cleverLinks": false,
    "monospaceLinks": false
  }
}

登录后复制

这个配置文件指定了 JSDoc 需要包含