How do we use jsddoc to document a callbacks return value that is passed in as a parameter as a function

Question

I currently document a javascript function and other code with the current jsdoc syntax (im welcome to change)

function exportStuff(dataObject) {
  /**
   *
   *  @param {Object} dataObject - some details about it
   *  @param {function} dataObject.animationStart
   *  @param {function} dataObject.ajax - when invoked, returns a promise/.thenable, but I want to know how to state that it does here in the jsdoc
   *  what if I tried:
   *  @callback {function} dataObject.ajax (not sure how to embed @param and @return here)
   *
   */

}

https://jsdoc.app/tags-callback.html doesnt make a ton of sense to me...but after looking at it more...maybe they mean in their example to define the param type as @param {requestCallback} then later as a separate comment we need to define @callback requestCallback and there document the @param and @returns for the definition

My question is a bit different because I want to use the jsdoc style but also know how to inline all in one single place (not separate) the param and returns types for the function passed in to be used as a callback (sorry for being repetitive)

Thanks for your time!

Cheers

Answer 1

The function type works like this:

function({paramTypes}):returnType

For example;

An event handler that returns nothing;

@param {function({Event}):void}

A standard sum method:

@param {function({number}, {number}):number}

The expected this type can be specified with:

@param {function(this:Foo):void}

The result of new type can be specified with:

@param {function(new:Foo):void}

You can also spread the operation:

@param {function(string, ...number): number}

Optional with = and nullable with ?:

@param {function(?string=, number=)}

-- Via Types in the Closure Type System.