# JSDoc 注释

> For the complete documentation index, see [llms.txt](https://www.jetbrains.com.cn/help/idea/llms.txt).

> **TL;DR**
> 必需插件  :
>
>
>
> `JavaScript 和 TypeScript` ：该插件与 IntelliJ IDEA 一起捆绑，并默认启用。

IntelliJ IDEA 可识别 [JSDoc 注释](https://jsdoc.app/)，并在输入块注释的开头  `/**`  并按下 `Enter` (Windows), `⏎` (macOS), `⏎` (IntelliJ IDEA Classic (macOS)), `⏎` (macOS System Shortcuts), `Enter` (XWin), `Enter` (GNOME), `Enter` (KDE), `Enter` (Emacs), `Enter` (Sublime Text), `⏎` (Sublime Text (macOS)), `Enter` (Visual Studio), `⏎` (Visual Studio (macOS)), `Enter` (NetBeans), `Enter` (Eclipse), `⏎` (Eclipse (macOS)) 时，自动插入  `@param` 、  `@returns` 、  `@private`  以及其他标记，帮助创建注释。 JSDoc 注释用于在 JavaScript 和 TypeScript 中通过 `Ctrl+Q` (Windows), `F1` (macOS), `⌃ J` (IntelliJ IDEA Classic (macOS)), `⌘ I` (macOS System Shortcuts), `Ctrl+Q` (XWin), `Ctrl+Q` (GNOME), `Ctrl+Q` (KDE), `Ctrl+Q` (Emacs), `Ctrl+Q` (Sublime Text), `Ctrl+Q` (Sublime Text (macOS)), `Ctrl+K, I` (Visual Studio), `⌘ K, I` (Visual Studio (macOS)), `Ctrl+Q` (NetBeans), `Alt+Middle-Click` (Eclipse), `⌥ Middle-Click` (Eclipse (macOS)) 进行文档查找，请参见 [JavaScript 文档查找](viewing-javascript-reference.html#view) 和 [TypeScript 文档查找](typescript-support.html#ws_ts_documentation_look_up)，以及在链式方法中用于 [类型注解](javascript-specific-guidelines.html#ws_js_type_hints) 和 [方法返回类型提示](javascript-specific-guidelines.html#ws_js_return_type_hints)。

IntelliJ IDEA 还可识别文档注释中的 [TODO 模式](using-todo.html)、 [Closure 编译器](https://github.com/google/closure-compiler/wiki/Annotating-JavaScript-for-the-Closure-Compiler)注解和 [TypeScript 语法](#ws_js_jsdoc_typescript_syntax)，并在代码补全、意图操作以及其他类型的编码辅助中使用它们。

在 [JSDoc 入门](https://jsdoc.app/about-getting-started.html) 和 [JSDoc 支持的类型](https://www.typescriptlang.org/docs/handbook/jsdoc-supported-types.html) 中查找包含示例的 JSDoc 语法详细说明。

## 创建 JSDoc 注释

Procedure:

* 将文本光标放在要记录的方法/函数或字段的声明前，键入起始块注释  `/**` ，然后按 `Enter` (Windows), `⏎` (macOS), `⏎` (IntelliJ IDEA Classic (macOS)), `⏎` (macOS System Shortcuts), `Enter` (XWin), `Enter` (GNOME), `Enter` (KDE), `Enter` (Emacs), `Enter` (Sublime Text), `⏎` (Sublime Text (macOS)), `Enter` (Visual Studio), `⏎` (Visual Studio (macOS)), `Enter` (NetBeans), `Enter` (Eclipse), `⏎` (Eclipse (macOS))。

IntelliJ IDEA 生成一个带有参数列表（  `@param` ）和返回值（  `@returns` ）的 JSDoc 注释，如果适用。 描述所列参数、返回值等。

![生成 jsdoc 注释](https://resources.jetbrains.com.cn/help/img/idea/2026.3/ws_insert_jsdoc_comment.animated.gif)

> **Tip:**
> 要关闭 JSDoc 注释的自动生成，请打开   设置  对话框（ `Ctrl+Alt+S` (Windows), `⌘ Comma` (macOS), `⌘ Comma` (IntelliJ IDEA Classic (macOS)), `⌘ Comma` (macOS System Shortcuts), `Ctrl+Alt+S` (XWin), `Ctrl+Alt+S` (GNOME), `Ctrl+Alt+S` (KDE), `Ctrl+Alt+S` (Emacs), `Ctrl+Alt+S` (Sublime Text), `⌘ Comma` (Sublime Text (macOS)), `Ctrl+Alt+S` (Visual Studio), `⌘ Comma` (Visual Studio (macOS)), `Ctrl+Alt+S` (NetBeans), `Ctrl+Alt+S` (Eclipse), `⌘ Comma` (Eclipse (macOS))），转到  `编辑器 | 常规 | 智能按键` ，并清除   插入文档注释存根  复选框中的   回车键  区域。

* 或者，使用专用的   修正文档注释   操作。 将文本光标置于要记录的方法/函数或字段处，按 `Ctrl+Shift+A` (Windows), `⌘ ⇧ A` (macOS), `⌘ ⇧ A` (IntelliJ IDEA Classic (macOS)), `⌘ ⇧ P` (macOS System Shortcuts), `Ctrl+Shift+A` (XWin), `Ctrl+Shift+A` (GNOME), `Ctrl+Shift+A` (KDE), `Escape, X` (Emacs), `Ctrl+Shift+P` (Sublime Text), `⌘ ⇧ P` (Sublime Text (macOS)), `Ctrl+Shift+A` (Visual Studio), `⌘ ⇧ A` (Visual Studio (macOS)), `Ctrl+I` (NetBeans), `Ctrl+Shift+A` (Eclipse), `⌘ 3` (Eclipse (macOS))并开始键入  `修正文档注释` 。 然后从列表中选择   修正文档注释  ，并按 `Enter` (Windows), `⏎` (macOS), `⏎` (IntelliJ IDEA Classic (macOS)), `⏎` (macOS System Shortcuts), `Enter` (XWin), `Enter` (GNOME), `Enter` (KDE), `Enter` (Emacs), `Enter` (Sublime Text), `⏎` (Sublime Text (macOS)), `Enter` (Visual Studio), `⏎` (Visual Studio (macOS)), `Enter` (NetBeans), `Enter` (Eclipse), `⏎` (Eclipse (macOS))。

## JSDoc 注释中的 TypeScript 语法

您可以在 JavaScript 文件中的 JSDoc 注释内使用 TypeScript 注解，例如，  `@type`  或  `@typedef` 。 IntelliJ IDEA 识别 TypeScript 语法结构，例如 [联合类型](https://www.typescriptlang.org/docs/handbook/2/everyday-types.html#union-types)或  `@typedef` 声明中的可选属性。

IntelliJ IDEA 为 TypeScript 注解提供代码补全。

![在 JavaScript 文件中为 JSDoc 中的 TypeScript 注释提供代码完成功能](https://resources.jetbrains.com.cn/help/img/idea/2026.3/ws_jsdoc_ts_syntax_completion.png)

根据  `@type` 注解，IntelliJ IDEA显示参数提示。

![参数提示基于 JavaScript 文件中 JSDoc 内的类型注解显示](https://resources.jetbrains.com.cn/help/img/idea/2026.3/ws_jsdoc_ts_syntax_parameter_hints.png)

> **Note:**
> 也支持混合类型。 但是，当 JSDoc 和 TypeScript 语法产生冲突时，IntelliJ IDEA 使用 JSDoc 语法。

## 在编辑器中查看 JSDoc 注释展示效果

通过 IntelliJ IDEA，JSDoc 注释可以以更易读的格式显示。 在此  呈现视图 模式中，项目按其  `@` 标签进行分组显示，而标签本身则被跳过。 您可以打开引用的网页、查看引用主题的快速文档，并调整字号以提高可读性。

![为 JSDoc 注释渲染视图](https://resources.jetbrains.com.cn/help/img/idea/2026.3/ws_js_preview_jsdoc_comments_rendered_in_the_editor.animated.gif)

> **Tip:**
> 渲染视图  模式在 JavaScript 和 TypeScript 中均可用。

Procedure:

* 进入  渲染视图 模式，请将鼠标悬停在评论上并点击 ![切换渲染视图图标](https://resources.jetbrains.com.cn/help/img/idea/2026.3/app.gutter.javadocRead.svg)或按下 `Ctrl+Alt+Q` (Windows), `⌃ ⌥ Q` (macOS), `⌃ ⌥ Q` (IntelliJ IDEA Classic (macOS)), `⌃ ⌥ Q` (macOS System Shortcuts), `Ctrl+Alt+Q` (XWin), `Ctrl+Alt+Q` (GNOME), `Ctrl+Alt+Q` (KDE), `Ctrl+Alt+Q` (Emacs), `Ctrl+Alt+Q` (Sublime Text), `⌃ ⌥ Q` (Sublime Text (macOS)), `Ctrl+K, V` (Visual Studio), `⌘ K, V` (Visual Studio (macOS)), `Ctrl+Alt+Q` (NetBeans), `Ctrl+Alt+Q` (Eclipse), `⌃ ⌥ Q` (Eclipse (macOS))。 图标变成 ![切换渲染视图图标](https://resources.jetbrains.com.cn/help/img/idea/2026.3/app.gutter.javadocEdit.svg)。

![打开渲染视图模式](https://resources.jetbrains.com.cn/help/img/idea/2026.3/turn_on_rendered_view.png)

* 退出  渲染视图 模式，点击 ![切换渲染视图图标](https://resources.jetbrains.com.cn/help/img/idea/2026.3/app.gutter.javadocEdit.svg)，或者从 JSDoc 注释的上下文菜单中选择   切换渲染视图  ，或按 `Ctrl+Alt+Q` (Windows), `⌃ ⌥ Q` (macOS), `⌃ ⌥ Q` (IntelliJ IDEA Classic (macOS)), `⌃ ⌥ Q` (macOS System Shortcuts), `Ctrl+Alt+Q` (XWin), `Ctrl+Alt+Q` (GNOME), `Ctrl+Alt+Q` (KDE), `Ctrl+Alt+Q` (Emacs), `Ctrl+Alt+Q` (Sublime Text), `⌃ ⌥ Q` (Sublime Text (macOS)), `Ctrl+K, V` (Visual Studio), `⌘ K, V` (Visual Studio (macOS)), `Ctrl+Alt+Q` (NetBeans), `Ctrl+Alt+Q` (Eclipse), `⌃ ⌥ Q` (Eclipse (macOS))。

![关闭 Rendered View 模式](https://resources.jetbrains.com.cn/help/img/idea/2026.3/turn_off_rendered_view.png)

* 要在当前文件中为所有 JSDoc 注释开启  Rendered View  模式，请从边栏的上下文菜单中选择   渲染所有文档注释​。  。

![将所有注释渲染到当前文件中](https://resources.jetbrains.com.cn/help/img/idea/2026.3/render_all_comments.png)

* 如有必要，请从上下文菜单中选择   调整字体大小  ，并使用滑块更改字体大小。

![调整字体大小](https://resources.jetbrains.com.cn/help/img/idea/2026.3/adjust_font_size.png)

* 要显示默认渲染的所有 JSDoc 注释，请打开   设置  对话框（ `Ctrl+Alt+S` (Windows), `⌘ Comma` (macOS), `⌘ Comma` (IntelliJ IDEA Classic (macOS)), `⌘ Comma` (macOS System Shortcuts), `Ctrl+Alt+S` (XWin), `Ctrl+Alt+S` (GNOME), `Ctrl+Alt+S` (KDE), `Ctrl+Alt+S` (Emacs), `Ctrl+Alt+S` (Sublime Text), `⌘ Comma` (Sublime Text (macOS)), `Ctrl+Alt+S` (Visual Studio), `⌘ Comma` (Visual Studio (macOS)), `Ctrl+Alt+S` (NetBeans), `Ctrl+Alt+S` (Eclipse), `⌘ Comma` (Eclipse (macOS))），转到  `编辑器 | 常规 | 外观` ，并选中   渲染文档注释  复选框。

![默认启用渲染的 JSDoc 注释](https://resources.jetbrains.com.cn/help/img/idea/2026.3/ws_js_preview_jsdoc_comments_rendered_checkbox.png)

* 要隐藏 Rendered View 槽图标，请从槽的上下文菜单中选择   配置装订区域图标…  ，然后在打开的  `设置 | 编辑器 | 常规 | 标记栏图标`  页面上取消选择   文档注释就地渲染   复选框。

## See also

### 过程

[快速文档](viewing-reference-information.html#inline-quick-documentation) [Javadocs](javadocs.html)

### 参考

[检查](inspections-settings.html)

### 外部链接

[https://github.com/jsdoc3/jsdoc/](https://github.com/jsdoc3/jsdoc/) [JSDoc toolkit](https://code.google.com/p/jsdoc-toolkit/) [Google Closure Compiler](https://github.com/google/closure-compiler/wiki/Annotating-JavaScript-for-the-Closure-Compiler)

