Search code examples
jsdoc

How to document callbacks using JSDoc?


Given a Javascript function that takes callback functions as parameters:

var myFunction = function(onSuccess, onFailure) {...}

How do I document onSuccess's return type and arguments?


Solution

  • In JSDoc 3.1 and later, you can use the new @callback tag to describe the callback function in a separate comment block. You can then refer to the callback in the docs for your method.

    Here's an example:

    /** @class */
    function MyClass() {}
    
    /**
     * Do something.
     * @param {MyClass~onSuccess} cb - Called on success.
     */
    MyClass.prototype.myFunction = function(cb) {
        // code
    };
    
    /**
     * Callback used by myFunction.
     * @callback MyClass~onSuccess
     * @param {number} resultCode
     * @param {string} resultMessage
     */
    

    See Use JSDoc for more information.