<p>JSDoc通过标准注释提升JavaScript代码可读性与维护性，支持类型标注和工具集成。使用/* /语法，结合@param、@returns、@type等标签定义参数、返回值和变量类型，如{number}、{Array<number>}、{string|number}；通过@typedef定义复杂对象结构，配合@type引用；支持可选参数、默认值、Promise及函数类型。在VS Code或TypeScript中启用checkJs可实现类型检查，无需迁移至TS即可获得静态类型优势，关键在于团队统一规范并结合开发工具使用。</p>
在JavaScript开发中，良好的文档注释不仅能提升代码可读性，还能帮助团队协作和工具支持（如IDE智能提示、类型检查等）。JSDoc 是一种广泛使用的文档注释规范，通过特定的语法为函数、变量、类等添加类型和说明信息。以下是 JSDoc 类型注释的核心规范与常用实践。
基本语法结构
JSDoc 注释以 /** 开头，每行以 * 起始，使用 @param、@return、@type 等标签描述代码元素。
示例：
/** * 计算两个数的和 * @param {number} a - 第一个加数 * @param {number} b - 第二个加数 * @returns {number} 两数之和 */ function add(a, b) { return a + b; }常用类型注释标签
以下是最常用的 JSDoc 标签及其用法：
立即学习“Java免费学习笔记（深入）”；
-
@param {type} name - description：标注函数参数的类型和说明。例如：
{string}、{Array<number>} - @returns {type} description 或 @return：标注返回值类型
- @type {type}：为变量或属性指定类型
- @typedef：定义自定义类型，便于复用复杂结构
- @property：用于对象类型中描述字段（常配合 @typedef 使用）
- @class 或 @constructor：标识构造函数或类
- @private、@public、@readonly：说明访问级别或属性状态
示例：使用 @typedef 定义对象结构
/** * @typedef {Object} User * @property {string} name - 用户名 * @property {number} age - 年龄 * @property {boolean} isActive - 是否激活 */
/* @type {User} / const user = { name: 'Alice', age: 28, isActive: true };
常见类型写法
JSDoc 支持多种类型表达方式，适配 JavaScript 的动态特性：
-
基础类型：
{string}、{number}、{boolean}、{null}、{undefined}、{function}、{object} -
数组：
{number[]}或{Array<number>} -
联合类型：
{string | number}表示可以是字符串或数字 -
可选参数：
@param {string} [name] - 可选的名字 -
默认值：
@param {string} [name="John"] - 带默认值的参数 -
回调函数：
{function(string, number): boolean}表示接受字符串和数字，返回布尔值的函数 -
Promises：
{Promise<string>}表示解析为字符串的 Promise
与现代开发工具集成
主流编辑器（如 VS Code）和构建工具（如 Webpack、ESLint）均支持 JSDoc 类型推断。配合 checkJs 和 allowJs 选项，TypeScript 编译器也能基于 JSDoc 提供类型检查。
示例：在 JS 文件中启用类型检查
// @ts-check/* @type {string} / let username = 123; // 错误：不能将 number 赋值给 string
这种方式无需完全迁移到 TypeScript，即可享受静态类型的好处。
基本上就这些。坚持使用 JSDoc 注释，能显著提升 JavaScript 项目的可维护性和开发效率。关键是保持一致性，并结合工具链发挥最大作用。
