JSDoc - how to document prototype methods

Question

I've been trying to document the following code using JSDoc:

/**
 * @module person
 */

 /**
  * A human being.
  * @class
  * @param {string} name
  */
function Person(name){
    this.name = name
}

Person.prototype = new function(){
    var amount_of_limbs = 4;

    /**
     * Introduce yourself
     */
    this.greet = function(){
        alert("Hello, my name is " + this.name + " and I have " + amount_of_limbs + " limbs");
    }
}

But the method greet is nowhere to be found in the resulting JSDoc documentation. What am I doing wrong?

Answer 1

It turned out I needed to use the @alias keyword. http://usejsdoc.org/tags-alias.html

Answer 2

Don't add prototype members like that. That's weird / bad / wrong.

You're setting the whole prototype of an existing object, rather than adding members to it. This will lead to performance problems, JS engine optimising issues and unexpected behaviour.

If you somehow need to overwrite the prototype, you should use Object.setPrototypeOf() method. Which is still not recommended even though it's a native method.

If your only problem is to "hide" some private constant, you have these options:

1. Use an IIFE (Immediately Invoked Function Expression):

/**
 * A human being.
 * @class
 */
var Person = (function () {

    // private variables
    var amountOfLimbs = 4;

    /**
     * Initializes a new instance of Person.
     * @constructs Person
     * @param {string} name
     */
    function Person(name) {
        /**
         * Name of the person.
         * @name Person#name
         * @type {String}
         */
        this.name = name
    }

    /**
     * Introduce yourself
     * @name Person#greet
     * @function
     */
    Person.prototype.greet = function () {
        alert("Hello, my name is " + this.name + " and I have " + amountOfLimbs + " limbs");
    };

    return Person;
})();

2. Use the conventional _ prefix for private vars/constants and use JSDoc @private tag.

/**
 * Person class.
 * @class
 */
function Person(name) {

    /**
     * Name of the person.
     * @name Person#name
     * @type {String}
     */
    this.name = name

    /**
     * Amount of limbs.
     * @private
     */
    this._amountOfLimbs = 4;
}

/**
 * Introduce yourself.
 * @name Person#greet
 * @function
 */
Person.prototype.greet = function () {
    alert("Hello, my name is " + this.name + " and I have " + this._amountOfLimbs + " limbs");
};

Answer 3

For prototypes I think you're just looking for @inheritdoc - http://usejsdoc.org/tags-inheritdoc.html or @augments/@extends - http://usejsdoc.org/tags-augments.html

I'm not sure that Onur's example is the correct use of prototypes. from my understanding the example creates a new instance of the prototype each time rather than linking to the same one so you don't really benefit in using them. If you're looking for code to function in that mannor a straight up factory or construcor function will do the job really well.

Perosnally I like the constructor approach as shown below, you may like the factory functions syntax better though and it probably gets more attention these days.

/**
 * A human being.
 * @constructor
 */
var person = function(name){
    // private variables
    var amount_of_limbs = 4;
    // public members
    this.name = name;

    /**
     * Introduce yourself
     */
    this.greet = function () {
        console.log("name is: "+this.name+" I have "+amount_of_limbs+" limbs"); 
    }.bind(this);

    return this;
};


var me = person.call({},'Michael');
me.greet(); //"name is: Michael I have 4 limbs"/

var you = person.call({},'Kuba');
you.greet(); //"name is: Kuba I have 4 limbs"/

Lastly; I don't think I could comment here without mentioning Kyle Simpsons OLOO pattern. It's a prototype delegation pattern which you may prefer to traditional prototypal syntax. There's more in his "You don't know JS" series and blog.

Answer 4

According to https://github.com/jsdoc3/jsdoc/issues/596 the correct answer would be: use @memberof

 /**
  * A human being.
  * @class
  * @constructor
  * @param {string} name
  */
function Person(name) { /*...*/ }
Person.prototype = {};
Person.prototype.constructor = Person;

/**
 * Perform a greeting.
 * @memberof Person
 */
Person.prototype.greet = function () { /*...*/ }

Answer 5

You can use @lends.

(function() {
    var amount_of_limbs = 4;

    MyClass.prototype = /** @lends MyClass# */ {
        /**
         * Introduce yourself
         */
        greet: function(){
            alert("Hello, my name is " + this.name + " and I have " + amount_of_limbs + " limbs");
        }
    };
})();

It is a slightly modified version. But the result is the same. You have a separate scope for a prototype.

From here.