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');

score 25 · Answer 1 · answered Jun 27 '18 at 14:35

25

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;
  }

answered Jun 27 '18 at 14:35

gforceg

421
5
8

You also don't need the parentheses: `@return {function: void}` works – Mike Harrison Jun 11 '21 at 19:38
This seems to work in VS Code, but doesn't pick up on the inner function documentation. :( – Aaron Campbell May 17 '22 at 21:34
I was able to use this one with parameters inside the parentheses: `@returns {(function([string], string, *, *): void)}`, doesn't seem to be possible to name them, though, but the IDEA, at least, parsing the types of the returned function. – extempl Jun 14 '23 at 05:15

score 24 · Answer 2 · edited Jun 30 '21 at 17:34

24

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;
}

edited Jun 30 '21 at 17:34

Zippy

3,826
5
43
96

answered May 22 '15 at 10:10

SGD

1,676
14
18

16

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
8

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
13

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
2

This doesn't seem to be recognized by VS Code. – Aaron Campbell May 17 '22 at 21:27

Aminadav Glickshtein · Accepted Answer · 2023-02-16T09:43:33.563

20

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;
  }

edited Feb 16 '23 at 09:43

answered Mar 22 '20 at 16:05

Aminadav Glickshtein

23,232
12
77
117

2

Is there any documentation for this? – Minh Nghĩa Aug 25 '20 at 05:57
1

Yeah, is this standard or non standard? – lance.dolan Dec 23 '20 at 15:16
Works in VSCode – Trevor Mar 04 '21 at 13:33
4

`promt` seems misspelt. – Pang Apr 08 '21 at 01:57
also works when I use tsc to generate .d.ts files – Mz A Jul 14 '22 at 11:10
Thanks. Edited. `promt` fixed to `prompt` – Aminadav Glickshtein Feb 16 '23 at 09:43

Magraina · Answer 4 · 2023-06-14T12:49:13.810

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');

> `@return {Function}` It never returns Function. Your example returns `void`. — extempl, Jun 14 '23 at 04:57

How to document a function returned by a function using JSDoc

4 Answers4

Linked