如何为类型化对象函数参数的字段做 Typescript JSDoc？答案

【问题标题】：How to do Typescript JSDoc for the fields of a typed object function parameter?如何为类型化对象函数参数的字段做 Typescript JSDoc？
【发布时间】：2021-08-20 01:55:00
【问题描述】：

下面是一个 Typescript 函数签名 x，它接受 ABC 作为可选参数。如果传入ABC，a和b是必填字段。

async x (options: ABC = {}): Promise<string> 

interface ABC {
  a: string
  b: number
}

JSDOC 应该是这样的

 /** 
   * @param {ABC} [options]
   * @param {string} options.a
   * @param {number} options.b
   * @return {Promise<string>} 
   */

或者这个

 /** 
   * @param {ABC} [options]
   * @param {string} [options.a]
   * @param {number} [options.b]
   * @return {Promise<string>} 
   */

【问题讨论】：

你需要JSDoc 和 Typescript吗？确定type SomeFunc = (options?: Options) => Promise<whatever> 就足够了吗？
商业目的需要
您能否修复您的代码，使其成为有效的 Typescript。我当然可以猜到，但你不应该让我们这样做。例如，您缺少 function 关键字。并且默认参数的类型错误。 a 和 b 应该是 ABC 的可选成员，还是应该 x 的 arg 具有不同的类型？

标签： javascript typescript jsdoc

【解决方案1】：

在ABC的JSDoc中记录ABC的结构，而不是在x的JSDoc中：

interface ABC {
    /**
     * describe `a` here
     */
    a: string

    /**
     * describe `b` here
     */
    b: number
}

/**
 * @param {ABC} options
 * @return {Promise<string>}
 */
async function x (options: ABC): Promise<string> {
    // IOU a promise
}

如果没有关于ABC.a 或ABC.b 的描述，您可以完全跳过该JSDoc。 Typescript 和您的 Typescript IDE 已经知道 a 是一个字符串，b 是接口定义中的一个数字。即使您提出的 JSDoc 是正确的（它不是），它也会是多余的。

? 问题中x 的签名会产生错误，所以我不得不猜测你的意图。请参阅我在问题下的评论。

【讨论】：