如何在JSDoc中记录特定格式的字符串参数？以日期参数为例

JSDoc 本身没有内置的专属类型来标记 yyyy-mm-dd 格式的日期字符串，所以核心还是得把格式说明写在注释里，但可以用更规范、易维护的方式呈现：

1. 基础清晰写法 #

直接在参数描述里明确格式，用强调突出格式要求，可读性强：

/**
 * 处理日期相关逻辑
 * @function dateStuff
 * @param {string} someDate - 日期字符串，格式要求为 *yyyy-mm-dd*
 */

2. 自定义类型复用（推荐） #

如果代码里多处用到这种格式的日期字符串，可以用 @typedef 自定义一个类型，后续直接引用，提升复用性和一致性：

/**
 * 符合 yyyy-mm-dd 格式的日期字符串
 * @typedef {string} YYYYMMDDDate
 */

/**
 * 处理日期相关逻辑
 * @function dateStuff
 * @param {YYYYMMDDDate} someDate - 日期字符串（格式：yyyy-mm-dd）
 */

3. TypeScript 扩展写法（非纯 JSDoc） #

如果你的项目结合了 TypeScript 并使用 JSDoc 类型注解，可以用字符串字面量类型来更精准约束，但这属于 TS 对 JSDoc 的扩展，不是纯 JSDoc 官方规范：

/**
 * 处理日期相关逻辑
 * @function dateStuff
 * @param {`${number}-${number}-${number}`} someDate - 日期字符串，格式必须为 yyyy-mm-dd
 */

总结一下：纯 JSDoc 官方规范里没有专门的标记来指定这种日期格式，最通用的就是在参数描述中明确说明；自定义类型的方式能让代码更整洁，适合多处复用的场景。

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