Search code examples
javascriptdocumentationjsdocjsdoc3

How to document a method with multiple aliases?

I'm trying to document the getName() method of The following Person constructor :

Javascript code :

/**
 * Creates a person instance.
 * @param {string} name The person's full name.
 * @constructor
 */
function Person( name ) {

    /**
     * Returns the person's full name.
     * @return {string} The current person's full name.
     */
    function getName() {
        return name;
    }

    this.getName = getName;
    this.getN = getName;
    this.getFullName = getName;
}

As you can see, the getName() method has two aliases ( getN() and getFullName() ), so the obvious tag to use is the @alias tag, but unfortunately, it has two major problems :

1- It tells JSDoc to rename the method.

2- It can't be used for multiple aliases.

Is there any official way to document these kind of methods ?

Solution

  • The answer to this question may sound a bit funny but, actually, there is an official way to document method aliases, and they call it @borrows .

    The @borrows tag allows you to add documentation for another symbol to your documentation.

    This tag would be useful if you had more than one way to reference a function, but you didn't want to duplicate the same documentation in two places.

    So, the getName() should be documented as follows:

    Javascript code :

    /**
 * Creates a person instance.
 * @param {string} name The person's full name.
 * @constructor
 * @borrows Person#getName as Person#getN
 * @borrows Person#getName as Person#getFullName
 */
function Person( name ) {

    /**
     * Returns the person's full name.
     * @return {string} The current person's full name.
     * @instance
     * @memberof Person
     */
    function getName() {
        return name;
    }

    this.getName = getName;
    this.getN = getName;
    this.getFullName = getName;
}

    JSDoc result :

    Result