带有注释参数属性的 Typescript jsdoc

Question

我正在尝试注释作为函数参数的对象的属性。

具体来说，当鼠标悬停在函数定义上时，我希望 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

我已经尽力copy from the docs但它不显示对 options.length 的解释。

我希望它显示对 options.length 参数如何工作的解释。我该怎么做？

奖金问题，也不确定如何使泛型与 jsdoc 一起工作...帮助 @template 非常感谢!

Answer 1

此行为似乎是一个已知错误，因此解构参数不会显示其 JSDoc 注释:microsoft/TypeScript#24746 .我不太确定为什么，但根据 a comment , 给一个 @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 开始工作，至少在将鼠标悬停在函数上时是这样。 (我认为当您将鼠标悬停在代码中名为 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 之外的任何内容。

---

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

/** 
 * @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 link to code