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

但我觉得有两个回报是不正确的，并没有说回归函数所期望的东西也不正确。这里的任何规则还是只是一种风格偏好？

Answer 1

我觉得有两个回报是不正确的

确实不是，函数只有一个返回值，而JSDoc只需要一个cum_max_s = as.POSIXct(cummin(as.numeric(StartTime)),origin="1970-01-01")。只要说出它实际上做了什么：

@return

Answer 2

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

我最终只为每个值得记录的函数编写了一个定义。由于箭头不需要和大括号来立即返回函数，我将返回函数移动到一个新行，然后在第一个函数和返回函数之间添加定义，并添加一个额外的缩进。我认为它在代码中看起来很好看，您可以使用@alias为匿名返回函数命名，并使用@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};
     };

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

2 个答案: