@augments

.. @augments::

语法

@augments <namepath>

同义词

@extends

概述

The @augments or@extends tag indicates that a symbol inherits from, and potentially adds to, a parent symbol. You can use this tag to document both class-based and prototype-based inheritance.

在JSDoc 3.3.0及更高版本中, 如果符号继承自多个父项, 并且两个父项具有相同名称的成员, 则JSDoc使用JSDoc注释中列出的最后一个父项的文档.

示例

在下面的例子中, Duck 类被定义为 Animal 的子类. Duck 实例与 Animal 实例具有相同的属性, 以及 duck 实例独有的 speak 方法.

Documenting a class/subclass relationship

/**
 * @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.

Multiple inheritance with duplicated method names

/**
 * 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() {
    // ...
};

.. @extends::

同义词

@augments