web-dev-qa-db-ja.com

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ドキュメントにはありません。私は何が間違っているのですか？

javascriptdocumentation-generationjsdoccode-documentationjsdoc3
17
Kuba Orlik

そのようなプロトタイプメンバーを追加しないでください。それは奇妙/悪い/間違っています。

メンバーを追加するのではなく、既存のオブジェクトのprototype全体を設定します。これはwillパフォーマンスの問題、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");
};
11
Onur Yıldırım

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 = Person;

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

@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");
        }
    };
})();

少し変更されたバージョンです。しかし、結果は同じです。プロトタイプ用に別のスコープがあります。

から ここ 。

0
FreeLightman

プロトタイプの場合は、@ 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"/

最後に;カイルシンプソンズのOLOOパターンに言及せずにここでコメントすることはできないと思います。これは、従来のプロトタイプ構文よりも好む可能性のあるプロトタイプ委任パターンです。彼の「あなたはJSを知らない」シリーズとブログにもっとあります。

0
Michael Hargreaves