如何为TypeScript类型化对象函数参数的字段编写JSDoc？——可选参数必填字段场景的注释方案辨析

咱们先对齐需求的核心逻辑：你的TypeScript函数里，options是可选参数（可以不传，默认是空对象），但只要你选择传入这个参数，那它必须符合ABC接口——也就是里面的a（字符串类型）和b（数字类型）是必填字段，不能省略。

接下来看两种写法的差异：

• 写法一：

  • @param {ABC} [options] 正确标记了options本身是可选参数；
  • @param {string} options.a 和 @param {number} options.b 没有加[]，这正好对应了“如果提供了options对象，那么a和b是必填属性”的规则。JSDoc里，嵌套属性的[]表示属性本身可选，这里我们不需要，因为ABC接口明确要求这两个字段必须存在。

• 写法二：
  给options.a和options.b加了[]，这会错误地传达一个信息：就算你传了options，a和b也可以选填。这完全和你的TypeScript接口定义矛盾，所以是错误的。

额外提一句：如果想让JSDoc的类型定义更清晰，你也可以用@typedef先定义ABC类型，但就当前给出的两个选项而言，写法一完全符合你的需求。

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