Typescript 带有注释参数属性的jsdoc

Question

我正在尝试注释 object 的属性，它是 function 的参数。

具体来说，当悬停在 function 定义上时，我希望options.length解释出现在 vscode 中。

/**
 * Memoize a function
 * @param  {(...fnArgs: T[]) => U} fn The function to memoize
 * @param  {Object} options Memoization options
 * @param  {number} options.max The max size of the LRU cache
 * @param  {number | undefined} options.length The response will be cached
 *  by the first N args, based on this value. Trailing args will still be
 *  passed to the underlying function but will be ignored during memoization.
 */
export const memo = <T, U>(
  fn: (...fnArgs: T[]) => U,
  { max, length }: { max: number; length?: number }
) => {
  const cachedArgs: T[][] = []
  const cachedValues: U[] = []
  const get = (args: T[]): U | undefined => {
    const index = cachedArgs.findIndex(x => argsAreEqual(x, args, length))
    if (index === -1) return
    onUsed(index)
    return cachedValues[index]
  }

  const set = (args: T[], value: U) => {
    cachedArgs.push(args)
    cachedValues.push(value)
  }

  const onUsed = (index: number) => {
    moveToEnd(index, cachedArgs)
    moveToEnd(index, cachedValues)
  }

  const prune = () => {
    if (cachedArgs.length >= max) {
      cachedArgs.shift()
      cachedValues.shift()
    }
  }
  return (...args: T[]) => {
    let value = get(args)
    if (value) return value
    prune()
    value = fn(...args)
    set(args, value)
    return value
  }
}

将鼠标悬停在类型签名上时，我得到以下信息

@param fn — The function to memoize
@param options — Memoization options

我已尽力从文档中复制，但它没有显示options.length的解释。

我希望它能够解释options.length参数的工作原理。 我怎样才能做到这一点？

额外的问题，不知道如何使 generics 与@template一起工作......非常感谢@template 的帮助！

Answer 1

这种行为似乎是一个已知的错误，其中解构参数没有显示其 JSDoc 注释： microsoft/TypeScript#24746 。 我不太确定为什么，但根据评论，给@param一个类型Object相当于给它一个类型any ，你可以通过使用不同的类型来获得你想要的行为。 在下面，我将Object更改为{} ：

/**
 * @param  {(...fnArgs: T[]) => U} fn
 * @param  {{}} options Memoization options
 * @param  {number} options.max The max size of the LRU cache
 * @param  {number | undefined} options.length The response will be cached
 *  by the first N args, based on this value. Trailing args will still be
 *  passed to the underlying function but will be ignored during memoization.
 */
export const memo = <T, U>(
  fn: (...fnArgs: T[]) => U,
  { max, length }: { max: number; length?: number }
) => { }

并且您的 IntelliSense 开始工作，至少在将鼠标悬停在 function 上时。 （我认为当您 hover 超过代码中名为max或length的实际标识符时，不可能得到评论）。 观察：

/* IntelliSense shows:
const memo: <T, U>(fn: (...fnArgs: T[]) => U, { max, length }: {
    max: number;
    length?: number | undefined;
}) => void   
@param fn  
@param options — Memoization options    
@param options.max — The max size of the LRU cache    
@param options.length — The response will be cached by the first N args,
  based on this value. Trailing args will still be passed to the
  underlying function but will be ignored during memoization.    
*/

请注意，这似乎只适用于TypeScript 代码（如.ts或.tsx ）而不是JavaScript 代码。 如果您在 JavaScript 中执行此操作，编译器将抱怨除Object或object之外的任何内容。

---

至于你的奖金问题，我认为它应该在 TypeScript 中工作，就像在 JavaScript 中一样：

/** 
 * @template T the arg type of fn
 * @template U the return type of fn
 * @param  {(...fnArgs: T[]) => U} fn

这向我展示了

/* IntelliSense shows:
const memo: <T, U>(fn: (...fnArgs: T[]) => U, { max, length }: {
    max: number;
    length?: number | undefined;
}) => void
@template — T the arg type of fn
@template — U the return type of fn 
@param fn
*/

Playground 代码链接