How to docstring a function arugument which is itself a function with arguments in JavaScript?

Question

How can I docstring an argument which is a function itself?

Example:

/**
 * 
 * @param secondFunction // I want to say this should be a function that accepts a number
 */
function firstFunction(secondFunction) {
    const a = 1;
    secondFunction(a);
}

Cheers!

Answer 1

From the JSDoc documentation:

Callback functions

If a parameter accepts a callback function, you can use the @callback tag to define a callback type, then include the callback type in the @param tag.

Parameters that accept a callback

/**
 * This callback type is called `secondFunction` and is displayed as a global symbol.
 *
 * @callback secondFunction
 * @param {number} a
 */

/**
 * executes secondFunction
 * @param {secondFunction} secondFunction - The callback
 */
function firstFunction(secondFunction) {
    const a = 1;
    secondFunction(a);
};

Answer 2

You can define the type of the parameter to be the function signature you expect to be passed:

/** Calls second function with 1
 * @param {(a:number)=>void} secondFunction
 */
function firstFunction(secondFunction) {
    const a = 1;
    secondFunction(a);
};