如何在 TypeScript 中使用 JSDoc 记录“提供者模式”功能？

Question

举一个最小的例子，这就是我所说的“提供者模式”function（如果这里有另一个名字，请纠正我）。

export const callEndpointProvider = (endpointToCall: string) => 
  async (accessToken: string): Promise<null> => { 
    return null 
  }

我想用 JSDoc 记录这个 function 以记录返回的 function，不一定是提供程序本身。

我在互联网上环顾四周，似乎找不到任何可以为我指明正确方向的东西，所以现在我已经足够记录提供者本身，就好像它是提供的 function 一样。

这种方法的问题是，在初始化提供程序后，我在提供的 function 上没有得到很好的 IDE 工具提示。

JSDoc 示例（目前我有）：

/**
* A function that returns null
* @async
* @return {null} - A null value
*/

如果有更适合这个用例的东西，我也愿意接受 JSDoc 的替代品，因为我们经常使用这种模式。

Answer 1

您可以通过将 JSDoc 放在 function 中，注释返回的 function 来做到这一点：

export const callEndpointProvider = (endpointToCall: string) => {
    /**
     * A function that returns null.
     *
     * @param   accessToken The access token to use.
     */
    return async (accessToken: string): Promise<null> => {
        return null;
    };
};

（由于您使用的是 TypeScript，因此类型不必在 JSDoc 中。）

下面是使用返回的 function 及其相关信息的示例（在本例中，通过 VS Code）：

当然，除了记录 function 本身之外：

/**
 * A function returning a function to call an endpoint.
 *
 * @param   endpointToCall  The endpoint the returned function will call.
 * @returns The function.
 */
export const callEndpointProvider = (endpointToCall: string) => {
    /**
     * A function that returns null.
     *
     * @param   accessToken The access token to use.
     */
    return async (accessToken: string): Promise<null> => {
        return null;
    };
};