带有注释参数的 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. I'm not really sure why, but according to 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

带有注释参数的 Typescript jsdoc 属性

Typescript jsdoc with annotate parameter property

jsdoc

typescript

visual-studio-code