How to document a function returned by a function using JSDoc

Question

I am using JSDoc for parameter documentation.

It is clear how to document the parameter types for many_prompts, but what is the right way to document the function it returns?

/**
 * @param {Number} - number of times to prompt
 * @return {Function(prompt{Number})} - the returned function
 */
function many_prompts(count) {
  return function(prompt) {
    for(var i=0; i < count; i++) alert(prompt);
  }
}


//Example of use:
var y  =many_prompts(3);
y('Hello World');

Answer 1

This seems to be working for me.

 /**
 * @param {Number} count - number of times to prompt
 * @return {function(): void} - the returned function
 */
  manyPrompts(count) {
      /**
       * My inner function
       *
       * @param {object} prompt Some parameter
       */
      const inner = function(prompt) {
        for (let i=0; i < count; i++) {
          alert(prompt);
        };
      };
      return inner;
  }

Answer 2

You can document the inner function and then reference it like so

/**
 * @param {Number} - number of times to prompt
 * @return {many_prompts~inner} - the returned function
 */
function many_prompts(count){
  /**
   * My inner function
   *
   * @param {object} prompt Some parameter
   */
  var inner = function(prompt){
    for(var i=0;i<count;i++) alert(prompt)
  };
  return inner;
}

Answer 3

The way I prefer:

/**
 * @param {number} count - number of times to prompt
 * @returns { (prompt:string) => void } - the returned function
 */
  manyPrompts(count) {
      /**
       * My inner function
       *
       * @param {object} prompt Some parameter
       */
      const inner = function(prompt) {
        for (let i=0; i < count; i++) {
          alert(prompt);
        };
      };
      return inner;
  }

Answer 4

This is my solution for this. I'm not describing a return in the first function and also document the inner function, which results in getting the documentation from the inner function.

/**
 * Function to create a Function with multiple prompt messages
 * @function
 * @param {Number} count - number of times to prompt
 */
function many_prompts(count) {
  /** 
   * To prompt a value multiple times
   * @function
   * @param {String} prompt - parameter to prompt
   * @return {void} prompt the input parameter
   */
  return function(prompt) {
    for(var i=0; i < count; i++) alert(prompt);
  }
}


//Example of use:
var y  = many_prompts(3);
y('Hello World');

---

Which is then shown e.g. in vscode like this...

For the outer function:

For the inner function:

---

You can also add an additional description when assigning the function, to describe the difference

/** 
 * Function to prompt a value 3 times
 * @function
 * @param {Number} prompt - parameter to prompt
 * @return {void} prompt the input parameter
 */
const y = many_prompts(3);
y('Hello World');