JSDoc参数注释是JavaScript中通过/* /语法描述函数参数的文档注释，使用@param标注类型、名称、可选性及默认值，如{number} a - 第一个加数，支持可选[silent]、默认值[name='Guest']及联合类型{string|number}，虽不影响运行，但能提升IDE智能提示、辅助类型检查、生成HTML文档并促进团队协作，增强代码可读性与维护性。
JavaScript 本身不支持像 Java 那样的“注解”（Annotation），但开发者常通过 JSDoc 工具在代码中添加参数注释，用于描述函数参数类型、作用等信息。这种注释方式虽不会影响运行，但能提升代码可读性，并被编辑器或构建工具识别，实现智能提示和类型检查。
什么是 JSDoc 参数注释
JSDoc 是一种用于 JavaScript 的文档注释语法，写在函数或变量上方，以 /** 开头，*/ 结尾。其中 @param 标签专门用来描述函数参数。
基本结构如下：
/**
* @param {类型} 参数名 - 说明文字
*/
@param 的详细写法
@param 支持指定参数类型、名称、是否可选、默认值以及描述信息。
-
基础类型注释：
/**
* 计算两数之和
* @param {number} a - 第一个加数
* @param {number} b - 第二个加数
* @returns {number} 和值
*/
function add(a, b) {
return a + b;
} -
可选参数标记：用方括号 [] 表示可选
/**
* 发送消息
* @param {string} text - 消息内容
* @param {boolean} [silent] - 是否静默发送（可选）
*/
function sendMessage(text, silent) { ... } -
带默认值的参数：可在描述中注明
/**
* 设置用户配置
* @param {Object} options - 配置项
* @param {string} [options.name='Guest'] - 用户名，默认为 'Guest'
* @param {number} [options.age=18] - 年龄，默认 18
*/ -
复杂类型与联合类型：
使用 {Object}、{Array} 或 {string|number} 等
/**
* 处理数据
* @param {Array} tags - 字符串标签数组
* @param {('info'|'warn'|'error')} level - 日志级别
*/
参数注释的作用
虽然 JSDoc 不改变 JS 运行逻辑，但它在开发过程中有实际价值：
- 增强 IDE 智能提示：VSCode、WebStorm 等编辑器能根据注释提示参数类型和说明。
- 辅助类型检查：配合 TypeScript 或 ESLint，可做静态分析，发现潜在错误。
- 生成项目文档：使用工具如 jsdoc 命令行可自动生成 HTML 文档。
- 团队协作更清晰：新人阅读代码时能快速理解函数用途和参数含义。
基本上就这些。合理使用 JSDoc 的 @param 注释，能让 JavaScript 代码更规范、易维护，尤其在大型项目或库开发中非常实用。
