带有注释参数属性的打字稿jsdoc答案

【问题标题】：Typescript jsdoc with annotate parameter property带有注释参数属性的打字稿jsdoc
【发布时间】：2021-06-09 13:17:39
【问题描述】：

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

具体来说，我希望在将鼠标悬停在函数定义上时，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 非常感谢！

【问题讨论】：

我从未使用过此功能，但也许您可以使用@prop 或@property 代替，例如this？
啊，这显然是一个已知的错误：microsoft/TypeScript#24746，其中列出了可能的解决方法。或者可能只是 TS 代码不支持它，如 microsoft/TypeScript#11859
this 解决方法对您有用吗？我不知道为什么Object 会阻止@param 工作，但相关问题似乎表明这会发生。
太棒了！如果你写一个答案将尽快批准。否则很高兴自己获得荣誉并写下答案！呵呵？？？？ @jcalz

标签： typescript visual-studio-code jsdoc

【解决方案1】：

这种行为似乎是一个已知的错误，即解构参数没有显示其 JSDoc cmets：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 的实际标识符上时，不可能获得 cmets）。观察：

/* 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

【讨论】：