Is there a way to document parameters of a function parameter?

Question

Say you have this function :

/**
 * doSomething description
 * @param {function} fn - A function that accepts an argument.
 */
function doSomething( fn ) {
    fn.call(this, 'This is a test');
}

And doSomething should be used like this :

doSomething( function( text ) {
    console.log( text );
});

My question is : Is there an official way in JSDoc to document fn parameters ? May be something like :

/**
 * doSomething description
 * @param {function} fn - A function that accepts an argument.
 * @param {string} fn( name ) - A text passed to the fn function.
 */
function doSomething( fn ) {
    fn.call(this, 'test');
}

No you won't find anything like that in JSDoc. Flow and TypeScript on the other hand... — Sergiu Paraschiv, Mar 11 '18 at 17:45
@SergiuParaschiv : Thank you so much, but is there a workaround or something ? — CryptoBird, Mar 11 '18 at 17:48
There's `@callback` though, maybe it's not a big deal to you that JSDoc thinks it's a callback :) http://usejsdoc.org/tags-param.html#callback-functions - this way at least you can specify parameter types. — Sergiu Paraschiv, Mar 11 '18 at 17:53
@SergiuParaschiv : I've seen that before posting the question, and I just don't like the way it separates the two functions. To be honest, I've never heard of Flow before.I looked it up on google and it seems cool.Thanks to you I'll start learning Flow . You are AWESOME :) — CryptoBird, Mar 11 '18 at 18:05
Flow is _awesome_ :) I've switched to TS myself because it brings a lot of other cool things besides strict type checking but if that's all you need then Flow should be plenty enough. Good luck with it! — Sergiu Paraschiv, Mar 11 '18 at 18:09
@SergiuParaschiv : You know what, since you've switched to TS after using Flow, I'm gonna start learning TS. Thanks for the advice. Keep it up :-) — CryptoBird, Mar 11 '18 at 18:18

score 2 · Accepted Answer · answered May 01 '18 at 16:50

As @SergiuParaschiv mentioned in his comment, the only way to do that is using the @callback tag like so :

Javascript code :

/**
 * A function to be passed as an argument.
 * @callback doSomethingCallback
 * @param {string} text - A simple text.
 */

 /**
  * doSomething description
  * @param {doSomethingCallback} fn - A function that accepts an argument.
  */
 function doSomething( fn ) {
     fn.call(this, 'This is a test');
 }

JSDoc result :

Is there a way to document parameters of a function parameter?

1 Answers1