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 ?

回答1:

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 :

来源：https://stackoverflow.com/questions/50125437/how-to-document-a-method-with-multiple-aliases

标签

javascript

documentation

jsdoc

jsdoc3