Javascript 如何正确注释部分应用的函数？

鉴于以下功能：

const sameCharactersAs = a=> b => 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}      
 */

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

我觉得有两次回报是不对的

实际上，函数只有一个返回值，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
 */

我觉得有两次回报是不对的

实际上，函数只有一个返回值，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
 */

---

您可以使用

@typedef

或

@callback

定义每个部分应用函数的返回类型。我不这么做，因为它看起来很时髦

最后，我只是为每个值得记录的函数编写了一个定义。由于箭头不需要大括号和大括号来立即返回函数，因此我将返回函数移到新行，然后在第一个函数和返回函数之间添加定义，并添加一个额外的缩进。我认为它最终在代码中看起来不错，您可以使用

@alias

为匿名返回函数命名，并使用

@link

在其他定义中引用函数

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

/**
*将多个装饰器合并到一个装饰器中。
*
*@example
*const Combined=组合计算器（Foo、Bar、Baz）；
*组合（分量）=Foo（Bar（Baz（分量））；
*
*@param{…Function}decorators-将组合的decorators。每个
*指定的装饰器将包装
*装修工。
*@返回{Function}合并的装饰函数。结果也是一个装饰
*并且可以传递回组合的装饰器
*/
常数组合计算器=(
…装饰器：数组
)：DecoratorType=>
/**
*{@link combineDecorators}返回的组合装饰器函数
*@alias组合除颤器
*@param{Function}WrappedComponent要修饰的组件
*@param{Object}config-将传递给每个
*装饰师
*@returns{Function}WrappedComponent和修饰
*/
(
WrappedComponent:类，
配置：decorConfigType，
)：Class=>
/**
*{@link combinedDecorator}返回的组件
*@alias wrappedcomponent fn
*@param{String}foo-foo
*@返回{Object}条
*/
（foo:string）=>{
const bar=decorators.reverse（）.reduce(
（WC，decorator）=>decorator（WC，config），
包装组件，
);
返回{…bar，foo}；
};

您可以使用

@typedef

或

@callback

定义每个部分应用函数的返回类型。我不这么做，因为它看起来很时髦

最后，我只是为每个值得记录的函数编写了一个定义。由于箭头不需要大括号和大括号来立即返回函数，因此我将返回函数移到新行，然后在第一个函数和返回函数之间添加定义，并添加一个额外的缩进。我认为它最终在代码中看起来不错，您可以使用

@alias

为匿名返回函数命名，并使用

@link

在其他定义中引用函数

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

/**
*将多个装饰器合并到一个装饰器中。
*
*@example
*const Combined=组合计算器（Foo、Bar、Baz）；
*组合（分量）=Foo（Bar（Baz（分量））；
*
*@param{…Function}decorators-将组合的decorators。每个
*指定的装饰器将包装
*装修工。
*@返回{Function}合并的装饰函数。结果也是一个装饰
*并且可以传递回组合的装饰器
*/
常数组合计算器=(
…装饰器：数组
)：DecoratorType=>
/**
*{@link combineDecorators}返回的组合装饰器函数
*@alias组合除颤器
*@param{Function}WrappedComponent要修饰的组件
*@param{Object}config-将传递给每个
*装饰师
*@returns{Function}WrappedComponent和修饰
*/
(
WrappedComponent:类，
配置：decorConfigType，
)：Class=>
/**
*{@link combinedDecorator}返回的组件
*@alias wrappedcomponent fn
*@param{String}foo-foo
*@返回{Object}条
*/
（foo:string）=>{
const bar=decorators.reverse（）.reduce(
（WC，decorator）=>decorator（WC，config），
包装组件，
);
返回{…bar，foo}；
};

我认为您也可以在单独的标记中定义函数，然后在

@return

中引用它。我真的不知道这是否是好的/广泛的实践（从来没有真正需要编写完全严格的JSDoc），但我认为这是可能的。当我不得不做这样的事情时，我只是使用了一点Hindley Milner符号

@返回字符串->字符串->布尔值

，这不是正确的JSDoc，但我发现它很好地描述了它（至少对于需要阅读它的人来说）。我认为您也可以在单独的标记中定义函数，然后在

@return

中引用它。我真的不知道这是否是好的/广泛的实践（从未真正需要编写完全严格的JSDoc）

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