如何正确评论部分应用的功能？

Question

给定以下函数：

const sameCharactersAs = a=> b => a.toLowerCase() === b.toLowerCase()

或

function sameCharactersAs(a){
  return function(b){
      return a.toLowerCase() === b.toLowerCase()
  }
}

上面的文档注释怎么写？我目前的做法是：

/**
 * checks if the strings have the same characters in the same order
 *
 * @param  {String} a   first string to check
 * @return {Function}   takes second string to check
 * @return {Bool}      
 */

但我觉得有两个 returns 是不正确的，而且没有说明返回函数的期望似乎也不正确。这里有什么规则还是只是风格偏好？

Answer 1

I feel like having two returns isn't correct

确实不是，一个函数只有一个 return 值，而 JSDoc 只需要一个 @return。只说它实际做了什么：

/**
 * Creates a function to test strings against the given string to see whether
 * they contain the same characters in the same order (case insensitive).
 *
 * @param  {String} a   The string
 * @return {Function}   A function that accepts a second string and returns `true`
 *                      if the second string matches the given string `a` (case
 *                      insensitive) or `false` if it doesn't
 */

Answer 2

您可以使用@typedef或@callback来定义每个偏应用函数的return类型。我不这样做，因为它看起来很时髦。

我最后只是为每个值得记录的函数写了一个定义。由于箭头不需要大括号直接 return 函数，我将 return 函数移到新行，然后在第一个函数和 [=21= 之间添加定义]ed 函数，带有额外的缩进。我认为它最终在代码中看起来不错，您可以使用 @alias 为匿名 return 函数命名，并使用 @link 在其他定义中引用函数。

一个示例（刚刚从一个项目中复制并稍作修改，对所有不必要的上下文和流类型的使用表示歉意）：

/**
 * Merge multiple decorators into one decorator.
 *
 * @example
 * const Combined = combineDecorators(Foo, Bar, Baz);
 * Combined(Component) == Foo(Bar(Baz(Component)));
 *
 * @param {...Function} decorators - Decorators that will be combined. Each
 *                                 decorator that is specifed will wrap the
 *                                 proceeding decorator.
 * @returns {Function} Merged decorator function. The result is also a decorator
 *                     and can be passed back into combineDecorators
 */
const combineDecorators = <DP, P, S>(
  ...decorators: Array<DecoratorType<DP, P, S>>
): DecoratorType<DP, P, S> =>
  /**
   * Combined decorator function that is returned by {@link combineDecorators}
   * @alias combinedDecorator
   * @param {Function} WrappedComponent Component to decorate
   * @param {Object} config - configuration that will be passed to each
   *                        decorator
   * @returns {Function} WrappedComponent with decorations
   */
  (
    WrappedComponent: Class<React$Component<DP, P, S>>,
    config: DecoratorConfigType,
  ): Class<React$Component<DP, P, S>> =>
    /**
     * Component that is returned by {@link combinedDecorator}
     * @alias WrappedComponentFn
     * @param {String} foo - foo
     * @returns {Object} bar
     */
     (foo: string) => {
       const bar = decorators.reverse().reduce(
         (WC, decorator) => decorator(WC, config),
         WrappedComponent,
       );
       return {...bar, foo};
     };

如何正确评论部分应用的功能？

How to properly comment a partially applied function?

javascript

documentation

jsdoc