JSDoc - 如何记录原型方法

Question

我一直在尝试使用 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");
    }
}

但是在生成的 JSDoc 文档中找不到方法 greet。我做错了什么？

Answer 1

不要添加这样的原型成员。这很奇怪/不好/错误。

您正在设置现有对象的整个prototype，而不是向其中添加成员。这将导致性能问题、JS 引擎优化问题和意外行为。

如果你需要覆盖原型，你应该使用Object.setPrototypeOf() 方法。即使它是本机方法，仍然不推荐。

如果你唯一的问题是“隐藏”一些私有常量，你有以下选择：

1. 使用 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. 对私有变量/常量使用常规的_ 前缀并使用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");
};

Answer 2

根据https://github.com/jsdoc3/jsdoc/issues/596，正确答案是：使用@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 3

您可以使用@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");
        }
    };
})();

这是一个稍微修改过的版本。但结果是一样的。您有一个单独的原型范围。

来自here。

Answer 4

对于原型，我认为您只是在寻找 @inheritdoc - http://usejsdoc.org/tags-inheritdoc.html 或@augments/@extends - http://usejsdoc.org/tags-augments.html

我不确定 Onur 的示例是否正确使用原型。据我了解，该示例每次都会创建一个原型的新实例，而不是链接到同一个实例，因此您不会真正受益于使用它们。如果您正在寻找以这种方式运行的代码，那么直接的工厂或构造函数会很好地完成这项工作。

就个人而言，我喜欢如下所示的构造函数方法，但您可能更喜欢工厂函数语法，并且这些天它可能会受到更多关注。

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

最后； 如果不提及 Kyle Simpsons 的 OLOO 模式，我认为我不能在这里发表评论。这是一种原型委托模式，您可能更喜欢传统的原型语法。他的“你不懂 JS”系列和博客中还有更多内容。

Answer 5

原来我需要使用@alias 关键字。 http://usejsdoc.org/tags-alias.html