带有注释参数属性的打字稿 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