如何在 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;
    };
};