Discussion: How to document curried functions using TSDoc

[beliayeu]

Does tsdoc support curried functions? Is there an example how a curried function can be documented?

Related tickets: jsdoc/jsdoc#1286 TypeStrong/typedoc#1098

[octogonz]

It also seems related to this JSDoc issue: jsdoc/jsdoc#1286

And this more general TSDoc discussion: #241

I have not thought about this much myself.

It would be helpful for someone to:

• share realistic examples of curried functions (with complete definitions for any other functions involved)
• propose some syntaxes for how TSDoc comments could be used to document them

[simonwjackson]

Cross post from: jsdoc/jsdoc#1286 (comment)

This is the only solution that worked for me:

const { curry, pathSatisfies } = require('ramda');

/**
 * Checks whether the given predicate is satisfied for the property value
 * at `propName` under `lambdaEvent.requestContext.authorizer`.
 *
 * @function
 * @see https://ramdajs.com/docs/#pathSatisfies
 * @param {Function} predicate The boolean returning function to apply to the
 *  value of the `propName` property.
 * @param {String} propName The name of the property to evaluate.
 * @returns {Boolean} The result of invoking `predicate` with the value of the
 *  property named `propName` on the `lambdaEvent.requestContext.authorizer` object.
 */

const authorizerPropSatisfies = curry(
  /** @type {(predicate: function, propName: string) => boolean} */
  (predicate, propName) => pathSatisfies(predicate, ['lambdaEvent', 'requestContext', 'authorizer', propName]),
);

module.exports = authorizerPropSatisfies;

The tradeoff: You have to declare types twice, once inside jsdoc and once just above the function declaration (and inside curry())

However, this doesn't feel completely unnatural as it resembles function declarations found in many FP languages