如何为Piped ES6函数生成JSDoc

Question

我有一个ES6样式的函数，该函数是使用组成函数定义的asyncPipe。

import { getItemAsync } from 'expo-secure-store';

const asyncPipe = (...fns) => x => fns.reduce(async (y, f) => f(await y), x);

const getToken = () => getItemAsync('token');

const liftedGetToken = async ({ ...rest }) => ({
  token: await getToken(),
  ...rest,
});

const liftedFetch = ({ body, route, token, method = 'GET' } = {}) =>
  fetch(route, {
    ...(body && { body: JSON.stringify(body) }),
    headers: {
      'Content-Type': 'application/json',
      ...(token && { Authorization: `Bearer ${token}` }),
    },
    method,
  });

const json = res => res.json();

/**
 * @method
 * @param {Object} fetchSettings the settings for the fetch request
 * @param {Object} fetchSettings.body the body of the request
 * @param {string} fetchSettings.route the URL of the request
 * @param {string} fetchSettings.method the method of the request
 * @param {string} fetchSettings.token should only be used for testing and unauthenticated requests
 */
const request = asyncPipe(liftedGetToken, liftedFetch, json);

如您所见，我尝试向其中添加JSDoc描述。但是，当我在任何地方使用它时，我的编辑器VSCode都不会建议其参数。如何使用JSDoc声明这些类型的函数？以及如何使此函数与Intellisense一起使用，需要获得参数？

Answer 1

VSCode将尝试在其中显示匿名函数的注释asyncPipe。如果在其中添加JSDoc注释，则可以看到以下行为：

const asyncPipe = (...fns) =>
  /**
   * My asyncPipe description
   * @param {Object} x Any object
   */
  x => fns.reduce(async (y, f) => f(await y), x);

const request = asyncPipe(liftedGetToken, liftedFetch, json);

不幸的是，JSDoc中无法像您尝试的那样覆盖匿名函数的文档。但是，您可以像这样将意图强加给VSCode，请注意，这会引入额外的函数调用：

const doRequest = asyncPipe(liftedGetToken, liftedFetch, json);

/**
 * @method
 * @param {Object} fetchSettings the settings for the fetch request
 * @param {Object} fetchSettings.body the body of the request
 * @param {string} fetchSettings.route the URL of the request
 * @param {string} fetchSettings.method the method of the request
 * @param {string} fetchSettings.token should only be used for testing and unauthenticated requests
 */
const request = fetchSettings => doRequest(fetchSettings);

Answer 2

VSCode 在底层使用 TypeScript 引擎，该引擎不擅长从函数组合推断类型，并且正如您所见，它无法将无点组合识别为函数声明。

如果需要类型提示，可以通过将指向的函数包裹在组合函数周围来指定该组合函数的参数。

我会这样写 - 注意：默认值使得 JSDoc 对于类型提示来说是不必要的，但无论如何，您可能希望保留 JSDoc 来进行描述。还要确保由默认值回退引起的故障会产生足够的错误消息。

/**
  * http request with JSON parsing and token management.
  * @param {Object} fetchSettings the settings for the fetch request
  * @param {Object} fetchSettings.body the body of the request
  * @param {string} fetchSettings.route the URL of the request
  * @param {string} fetchSettings.method the method of the request
  * @param {string} fetchSettings.token should only be used for testing and unauthenticated requests
  */
const request = ({
  body = {},
  route = '',
  method = 'GET',
  token = ''
}) => asyncPipe(liftedGetToken, liftedFetch, json)({
  body, route, method, token
});