JSDoc - как документировать прототипы методов

Я пытался документировать следующий код с помощью 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");
    }
}

Но метод greet нигде не встречается в результирующей документации JSDoc. Что я делаю неправильно?

Ответы

Ответ 1

Не добавляйте такие элементы прототипа. Это странно/плохо/неправильно.

Вы устанавливаете весь prototype существующего объекта, а не добавляете к нему участников. Эта будет приводить к проблемам с производительностью, оптимизации JS-движка и неожиданному поведению.

Если вам нужно как-то переписать прототип, вы должны использовать метод Object.setPrototypeOf(). Это еще не рекомендуется, даже если это собственный метод.

Если ваша единственная проблема - "скрыть" какую-то частную константу, у вас есть следующие параметры:

  • Использовать IIFE (выражение с выведенным вызовом):
/**
 * 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;
})();
  1. Используйте обычный префикс _ для частных vars/констант и используйте тег JSDoc @private.
/**
 * 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");
};

Ответ 2

Для прототипов я думаю, что вы просто ищете @inheritdoc - http://usejsdoc.org/tags-inheritdoc.html или @augments/@extends - http://usejsdoc.org/tags-augments.html

Я не уверен, что пример Onur - это правильное использование прототипов. из моего понимания, пример каждый раз создает новый экземпляр прототипа, а не связывается с одним и тем же, поэтому вам не выгодно использовать их. Если вы ищете код, который будет функционировать в этом mannor, функция up factory или construcor сделает работу действительно хорошо.

Perosnally Мне нравится подход к конструктору, как показано ниже, вам может понравиться синтаксис функций factory, хотя и, вероятно, в наши дни он получает больше внимания.

/**
 * 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"/

Наконец, Я не думаю, что могу прокомментировать здесь, не упоминая образ Кайла Симпсонов OLOO. Это образец шаблона прототипа, который вы можете предпочесть традиционному прототипному синтаксису. Там больше в его серии "Вы не знаете JS" и в блоге.

Ответ 3

В соответствии с https://github.com/jsdoc3/jsdoc/issues/596 правильный ответ: use @memberof

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

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

Ответ 4

Вы можете использовать @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");
        }
    };
})();

Это слегка измененная версия. Но результат тот же. У вас есть отдельный пробел для прототипа.

Из здесь.