38

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');
Alexander
  • 3,922
  • 7
  • 24
  • 34
Aminadav Glickshtein
  • 17,003
  • 10
  • 63
  • 99

3 Answers3

21

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;
}
SGD
  • 1,601
  • 12
  • 18
  • 11
    Is there a way to do this for anonymous inner functions? – Jack Allan May 20 '16 at 08:20
  • For JSDoc you would need some form of reference, I guess it depends on how the anonymous function is used. Do you have an example? – SGD May 20 '16 at 16:06
  • 5
    Is this documented anywhere officially? Can't find it. – Ben Creasy Jun 28 '17 at 03:58
  • Not in full depth I'm afraid. Did you try tagging your inner function with `@function many_prompts~inner` – SGD Jul 25 '17 at 11:56
  • 11
    Is there a way to do this if you're using arrow functions? For instance: `many_prompts = count => prompt => ...` – Lucretiel Dec 15 '17 at 02:37
  • I have never tried, theoretically it should work as it is semantically the same but the question is if the available parsers do support this already. – SGD Jan 09 '18 at 14:12
12

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;
  }
gforceg
  • 191
  • 1
  • 7
9

The way I prefer:

/**
 * @param {number} count - number of times to prompt
 * @returns { (promt: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;
  }
Aminadav Glickshtein
  • 17,003
  • 10
  • 63
  • 99