@use JSDoc

関連語

構文

@augments <namepath>

概要

@augmentsまたは @extendsタグは、シンボルが親シンボルから継承し、追加する可能性があることを示します。このタグを使用して、クラスベースとプロトタイプベースの継承の両方をドキュメント化できます。

JSDoc 3.3.0以降では、シンボルが複数の親から継承し、両方の親にまったく同じ名前のメンバーがある場合、JSDocはJSDocコメントに記載されている最後の親からのドキュメントを使用します。

例

次の例では、DuckクラスはAnimalのサブクラスとして定義されます。Duckインスタンスは、Animalインスタンスと同じプロパティを持ち、さらにDuckインスタンスに固有のspeakメソッドを持ちます。

クラス/サブクラス関係のドキュメント化
/**
 * @constructor
 */
function Animal() {
    /** Is this animal alive? */
    this.alive = true;
}

/**
 * @constructor
 * @augments Animal
 */
function Duck() {}
Duck.prototype = new Animal();

/** What do ducks say? */
Duck.prototype.speak = function() {
    if (this.alive) {
        alert('Quack!');
    }
};

var d = new Duck();
d.speak(); // Quack!
d.alive = false;
d.speak(); // (nothing)

次の例では、DuckクラスはFlyableとBirdの両方のクラスから継承し、どちらもtakeOffメソッドを定義します。Duckのドキュメントで@augments Birdが最後にリストされているため、JSDocはDuck#takeOffをBird#takeOffのコメントを使用して自動的にドキュメント化します。

メソッド名が重複した多重継承
/**
 * Abstract class for things that can fly.
 * @class
 */
function Flyable() {
    this.canFly = true;
}

/** Take off. */
Flyable.prototype.takeOff = function() {
    // ...
};

/**
 * Abstract class representing a bird.
 * @class
 */
function Bird(canFly) {
    this.canFly = canFly;
}

/** Spread your wings and fly, if possible. */
Bird.prototype.takeOff = function() {
    if (this.canFly) {
        this._spreadWings()
            ._run()
            ._flapWings();
    }
};

/**
 * Class representing a duck.
 * @class
 * @augments Flyable
 * @augments Bird
 */
function Duck() {}

// Described in the docs as "Spread your wings and fly, if possible."
Duck.prototype.takeOff = function() {
    // ...
};