如何使用JSDoc编写React组件onChange回调的参数说明供开发者参考

现有注释的不合理之处 #

• 类型标注错误：@type {string} 和 onChange 是回调函数的属性属性完全不符，会严重误导使用组件的开发者
• 参数定义模糊：@param {*} 没有明确标注 onChange 的函数类型，也没有说明回调入参的实际含义
• 描述信息无效：仅写(value: any) => void没有说明value的具体类型（是Date对象还是格式化字符串），对开发者没有实际指导意义

优化后的JSDoc写法 #

你可以根据你的组件实际返回的日期格式，选择下面两种写法之一：

写法1：更详细的分层标注（可读性更高）

/**
 * 内联日期选择组件
 * @component DatePicker
 * @param {Function} onChange - 选中日期发生变化时触发的回调函数
 * @param {Date} onChange.date - 回调入参：当前选中的日期对象，若组件返回格式化字符串则改为{string}
 * @returns {void} 组件无返回值
 */

写法2：更简洁的函数类型直接标注（IDE提示更精准）

/**
 * 内联日期选择组件
 * @component DatePicker
 * @param {(date: Date) => void} onChange - 选中日期发生变化时触发的回调，入参为当前选中的日期对象
 * @returns {void} 组件无返回值
 */

优化效果 #

两种写法都可以被主流IDE正确识别，开发者在绑定onChange回调时，会自动获得参数类型提示，不需要额外查阅文档就能知道回调接收的是日期值，完全匹配你给出的handleDateChange使用示例要求。

内容的提问来源于stack exchange，提问作者user12302978