Multiple function signatures

[Adam Powers]

I have a few constructors and methods that dynamically parse arguments and deserve different documentation for the different types of arguments and behaviors. Using Sinon Spies as an example, my code is something like this:

/** A class for spying on functions */
class Spy {
    /** Constructs a new spy */
    constructor() {
        /**
         * First constructor signature. Creates an anonymous function that records arguments, this value, exceptions and return values for all calls.
         * @return {Function} A new empty spy
         * @constructs Spy
         */
        if (arguments.length === 0) {
            // return a new spy
        }
        /**
         * Second constructor signature. Spies on the provided function.
         * @param {Function} myFunc The function to be spied on
         * @returns {Function} The spy-wrapped function
         * @constructs Spy
         */
        if (arguments.length === 1 && typeof argument[0] === "function") {
            // return a wrapped function
        }
        /**
         * Third constructor signature. Creates a spy for object.method and replaces the original method with the spy.
         * @param  {Object} obj    The object where 'method' resides
         * @param  {String} method The method to wrap in a spy
         * @return {Object}        The object that has the freshly wrapped method
         * @constructs Spy
         */
        if (arguments.length === 1 &&
            typeof argument[0] === "object" &&
            typeof argument[1] === "string") {
            // return object with a freshly wrapped method
        }
    }
    /** Checks whether the spy-wrapped function threw an error */
    threw() {
        /**
         * First threw signature. Returns true if call threw an exception.
         * @return {Boolean} True if spy-wrapped function threw an error, false otherwise
         */
        if (arguments.length === 0) {
            // do stuff...
        }
        /**
         * Second threw signature. Returns true if call threw exception of provided type.
         * @param {String} TypeError The type of error expected to be thrown
         * @return {Boolean} True if spy-wrapped function threw an error of the type specified, false otherwise
         */
        if (arguments.length === 1 && typeof arguments[0] === "string") {
            // do stuff...
        }
        /**
         * Second threw signature. Returns true if call threw provided exception object.
         * @param {String} obj The type of error expected to be thrown
         * @return {Boolean} True if spy-wrapped function threw an error of the object specified, false otherwise
         */
        if (arguments.length === 1 && typeof arguments[0] === "object") {
            // do stuff...
        }
    }
}

 

Is there any way to change the JSDoc code so that the documentation reflects the different function signatures? I'm indifferent as to what the documentation formatting is (three functions with the same name; one function with different descriptions & parameters; etc).

 

[Osher El-Netanany]

IMHO - this will be a misleading documentations.

In JS you actually have just one function, and like your logic implies - you chose what to do by the number and type of arguments.

What I do is a combination of the following:

1 - use OR symbol, and explain verbally the implication of the type

/**

@param {string|number} code - a textual search, or an ID

*/

function getItem(code) { ... }

2 - mark optional parameters

/**

@param {number} dept - the department code

@param {number|optional} limit - max items to return, when ommitted, 20 items returned

*/

function getProducts(dept, limit) { ... }

I once saw somewhere an @optionalParam custom tag that was supposed to work like this:

/**

@param {number} dept - the department code

@optionalParam {number|optional} limit - max items to return, when ommitted, 20 items returned

*/

but I never got it working, and got bye without it, so I never put more effort beyond the first try.

--
You received this message because you are subscribed to the Google Groups "JSDoc Users" group.
To unsubscribe from this group and stop receiving emails from it, send an email to jsdoc-users+unsubscribe@googlegroups.com.
To post to this group, send email to jsdoc...@googlegroups.com.
Visit this group at https://groups.google.com/group/jsdoc-users.
To view this discussion on the web visit https://groups.google.com/d/msgid/jsdoc-users/290d181e-6ac3-4daf-a56d-d459e04ebccb%40googlegroups.com.
For more options, visit https://groups.google.com/d/optout.