如何记录返回 function 调用的 function 调用（用于尾调用优化）

Question

I'm trying to skill up on JSDoc, and I have this method:

/**
 * Cleanup step.
 *
 * @return {Void}
 */
beforeDestroy() {
    window.removeEventListener('resize', this.onResize);
},

That seems correct, but for my normal JavaScript coding-style, I would have this:

beforeDestroy() {
    return window.removeEventListener('resize', this.onResize);
},

because I always try to return a function call if I can (as a functional programming habit related to tail call optimization). This leads me to my question of, how do I document a function that returns a function call?

My naive estimate is it would be something like this:

/**
 * Cleanup step.
 *
 * @return {(String, Function) => Void}
 */
beforeDestroy() {
    return window.removeEventListener('resize', this.onResize);
},

I'd like to hear about what correct/normal is for this kind of thing. I'd like to know how to document like this where the function "returns a function-call that returns void" or also something else like "returns a function-call that returns a string".

I've seen people ask about curried functions before, and this kind of gets out of hand immediately for me with respect to documention, like how many functions does a person need?

Something like this seems unreasonable to me:

 * @return {(String, Function) => (Object) => Void}

Like how much awareness of future execution does the "doc" need?

Answer 1

You use a @callback (or @function ); see: https://jsdoc.app/tags-callback.html

For instance, something like.

/**
 * This callback is a returned event listener
 * @callback removedCallback
 * @param {number} nameOfNumberParam
 * @param {string} nameOfStringParam
 */

/**
 * Cleanup step.
 *
 * @return {removedCallback} - The removed callback
 */
beforeDestroy() {
    return window.removeEventListener('resize', this.onResize);
},

However, you also want to ask yourself... is this really going to be useful to anyone, or am I documenting just to document? If what you're really going for is a type system, then Typescript can do that much better (and give you lots of other benefits besides just documentation).

If you are just going for documentation, consider your audience. For some audiences the above style will be best, but many others might be just as well served with a simpler:

/**
 * Cleanup step.
 *
 * @return function - The removed callback
 */
beforeDestroy() {
    return window.removeEventListener('resize', this.onResize);
},