@augments

Содержание

Синонимы
Синтаксис
Обзор
Примеры
Связанные ссылки

Синонимы

@extends

Синтаксис

@augments <namepath>

Обзор

Тег @augments или @extends указывает, что символ наследуется от родительского символа и, возможно, добавляет к нему новые свойства. Вы можете использовать этот тег для документирования наследования как на основе классов, так и на основе прототипов.

В JSDoc 3.3.0 и более поздних версиях, если символ наследуется от нескольких родителей, и оба родителя имеют члены с одинаковыми именами, JSDoc использует документацию из последнего родительского элемента, указанного в комментарии JSDoc.

Примеры

В следующем примере класс Duck определён как подкласс Animal. Экземпляры Duck обладают теми же свойствами, что и экземпляры Animal, а также методом speak, который уникален для экземпляров Duck.

Документирование отношений класса/подкласса

/**
 * @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 автоматически использует комментарий из Bird#takeOff для документации Duck#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() {
    // ...
};