Markiert eine Methode als abstrakt. Ähnlich wie beim Festlegen einer Methode auf goog.abstractMethod kann der Compiler Methoden entfernen, die mit @abstract gekennzeichnet sind, um die Codegröße zu reduzieren.

Der Compiler gibt eine Warnung aus, wenn eine mit @abstract gekennzeichnete Methode eine nicht leere Implementierung aufweist.

/** @abstract */
foo.MyClass.prototype.abstractMethod = function() {};

Kennzeichnet eine Variable als schreibgeschützt. Der Compiler kann @const-Variablen inline einbinden, wodurch der JavaScript-Code optimiert wird.

Die Typdeklaration ist optional.

Der Compiler gibt eine Warnung aus, wenn einer mit @const markierten Variable mehr als einmal ein Wert zugewiesen wird. Wenn die Variable ein Objekt ist, sind Änderungen an den Eigenschaften des Objekts nicht zulässig.

/** @const */ var MY_BEER = 'stout';

/**
 * My namespace's favorite kind of beer.
 * @const {string}
 */
mynamespace.MY_BEER = 'stout';

/** @const */ MyClass.MY_BEER = 'stout';

Kennzeichnet eine Funktion als Konstruktor. Der Compiler benötigt eine @constructor-Annotation für jede Funktion, die mit dem Schlüsselwort new verwendet wird.

Beispiel:

/**
 * A rectangle.
 * @constructor
 */
function GM_Rect() {
  ...
}

Beispiel:

/** @define {boolean} */
var ENABLE_DEBUG = true;

/** @define {boolean} */
goog.userAgent.ASSUME_IE = false;

Kennzeichnet eine Funktion, Methode oder Eigenschaft, sodass eine Compiler-Warnung angezeigt wird, die besagt, dass sie nicht mehr verwendet werden sollte.

Beispiel:

/**
 * Determines whether a node is a field.
 * @return {boolean} True if the contents of
 *     the element are editable, but the element
 *     itself is not.
 * @deprecated Use isField().
 */
BN_EditUtil.isTopEditableField = function(node) {
  ...
};

Mit @dict werden Objekte mit unterschiedlichen Attributen erstellt. Wenn ein Konstruktor (im Beispiel Foo) mit @dict annotiert ist, können Sie nur die eckige Klammer verwenden, um auf die Attribute von Foo-Objekten zuzugreifen. Die Annotation kann auch direkt für Objektliterale verwendet werden.

Beispiel:

/**
 * @constructor
 * @dict
 */
function Foo() {}
var obj1 = new Foo();
obj1['x'] = 123;
obj1.x = 234;  // warning

var obj2 = /** @dict */ { 'x': 321 };
obj2.x = 123;  // warning

Gibt den Typ einer Aufzählung an. Ein Enum ist ein Objekt, dessen Attribute eine Gruppe verwandter Konstanten ergeben. Auf das @enum-Tag muss ein Typausdruck folgen.

Das Typlabel einer Aufzählung gilt für jedes Attribut der Aufzählung. Wenn eine Aufzählung beispielsweise den Typ number hat, muss jede ihrer Enum-Attribute eine Zahl sein. Wird der Typ einer Aufzählung weggelassen, wird number verwendet.

Beispiel:

/**
 * Enum for tri-state values.
 * @enum {number}
 */
project.TriState = {
  TRUE: 1,
  FALSE: -1,
  MAYBE: 0
};

Mit diesem Code

/** @export */
foo.MyPublicClass.prototype.myPublicMethod = function() {
  // ...
};

Wenn der Compiler mit dem Flag --generate_exports ausgeführt wird, generiert er den Code:

goog.exportProperty(foo.MyPublicClass.prototype, 'myPublicMethod',
  foo.MyPublicClass.prototype.myPublicMethod);

Dadurch werden die Symbole in unkompilierten Code exportiert. Sie können /** @export {SomeType} */ als Kurzschreibweise für

/**
 * @export
 * @type {SomeType}
 */

Code, der die Annotation @export verwendet, muss entweder

1. closure/base.js einschließen oder
2. sowohl goog.exportSymbol als auch goog.exportProperty mit derselben Methodensignatur in ihrer eigenen Codebasis definieren.

Kennzeichnet eine Klasse oder Schnittstelle als von einer anderen Klasse übernommen. Eine mit @extends gekennzeichnete Klasse muss auch mit @constructor oder @interface gekennzeichnet sein.

Hinweis: @extends bewirkt nicht, dass eine Klasse von einer anderen Klasse übernimmt. Die Annotation teilt dem Compiler einfach mit, dass er eine Klasse während der Typprüfung als abgeleitete Klasse einer anderen behandeln kann.

Ein Beispiel für die Implementierung der Übernahme finden Sie unter Funktion „Closure Library“ goog.inherits().

Beispiel:

/**
 * Immutable empty node list.
 * @constructor
 * @extends {goog.ds.BasicNodeList}
 */
goog.ds.EmptyNodeList = function() {
  ...
};

Gibt an, dass diese Klasse nicht erweitert werden darf. Gibt für Methoden an, dass keine Unterklasse diese Methode überschreiben kann.

Beispiel:

/**
 * A class that cannot be extended.
 * @final
 * @constructor
 */
sloth.MyFinalClass = function() { ... }

/**
 * A method that cannot be overridden.
 * @final
 */
sloth.MyFinalClass.prototype.method = function() { ... };

Wird mit @constructor verwendet, um anzugeben, dass eine Klasse eine Schnittstelle implementiert.

Der Compiler gibt eine Warnung aus, wenn Sie einen Konstruktor mit @implements taggen und dann nicht alle von der Schnittstelle definierten Methoden und Attribute implementieren.

Beispiel:

/**
 * A shape.
 * @interface
 */
function Shape() {};
Shape.prototype.draw = function() {};

/**
 * @constructor
 * @implements {Shape}
 */
function Square() {};
Square.prototype.draw = function() {
  ...
};

Diese Annotation kann nur in externen Property-Deklarationen angezeigt werden. Die Eigenschaft hat einen deklarierten Typ, aber Sie können ihr einen beliebigen Typ ohne Warnung zuweisen. Beim Zugriff auf die Property wird ein Wert des deklarierten Typs zurückgegeben. element.innerHTML kann beispielsweise ein beliebiger Typ zugewiesen werden, es wird jedoch immer ein String zurückgegeben.

/**
 * @type {string}
 * @implicitCast
 */
Element.prototype.innerHTML;

Gibt an, dass eine Methode oder Eigenschaft einer abgeleiteten Klasse absichtlich eine Methode oder Eigenschaft der übergeordneten Klasse verbirgt und genau dieselbe Dokumentation hat. Das Tag @inheritDoc impliziert das Tag @override.

Beispiel:

/** @inheritDoc */
project.SubClass.prototype.toString = function() {
  ...
};

Kennzeichnet eine Funktion als Schnittstelle. Eine Schnittstelle gibt die erforderlichen Mitglieder eines Typs an. Jede Klasse, die eine Schnittstelle implementiert, muss alle Methoden und Attribute implementieren, die auf dem Prototyp der Schnittstelle definiert sind. Weitere Informationen finden Sie unter @implements.

Der Compiler überprüft, ob Schnittstellen nicht instanziiert sind. Wenn das Schlüsselwort new mit einer Schnittstellenfunktion verwendet wird, gibt der Compiler eine Warnung aus.

Beispiel:

/**
 * A shape.
 * @interface
 */
function Shape() {};
Shape.prototype.draw = function() {};

/**
 * A polygon.
 * @interface
 * @extends {Shape}
 */
function Polygon() {};
Polygon.prototype.getSides = function() {};

Gibt an, dass die Schlüssel eines Objektliterals als Attribute eines anderen Objekts behandelt werden sollen. Diese Annotation sollte nur für Objektliterale angezeigt werden.

Beachten Sie, dass der Name in geschweiften Klammern kein Typname wie in anderen Annotationen ist. Es ist ein Objektname. Sie benennt das Objekt, an das die Properties gemietet werden. @type {Foo} bedeutet beispielsweise „eine Instanz von Foo“, aber @lends {Foo} bedeutet „der Konstruktor Foo“.

Weitere Informationen zu dieser Annotation finden Sie in den JSDoc Toolkit-Dokumenten.

Beispiel:

goog.object.extend(
    Button.prototype,
    /** @lends {Button.prototype} */ ({
      isButton: function() { return true; }
    }));

Weist den Compiler an, den zugehörigen Kommentar vor dem kompilierten Code für die markierte Datei einzufügen. Mit dieser Annotation können wichtige Hinweise wie rechtliche Lizenzen oder Urheberrechtstexte weiterhin kompiliert werden. Zeilenumbrüche werden beibehalten.

Beispiel:

/**
 * @preserve Copyright 2009 SomeThirdParty.
 * Here is the full license text and copyright
 * notice for this file. Note that the notice can span several
 * lines and is only terminated by the closing star and slash:
 */

Gibt ein Attribut an, das vom Compiler nicht in eine Variable minimiert werden soll. Der primäre Zweck von @nocollapse besteht darin, das Exportieren änderbarer Attribute zu ermöglichen. Beachten Sie, dass nicht minimierte Attribute vom Compiler weiterhin umbenannt werden können. Wenn Sie eine Property, die ein Objekt mit @nocollapse ist, mit einer Anmerkung versehen, bleiben alle ihre Attribute ebenfalls minimiert.

Beispiel:

/**
 * A namespace.
 * @const
 */
var foo = {};

/**
 * @nocollapse
 */
foo.bar = 42;

window['foobar'] = foo.bar;

Gibt an, dass ein Aufruf der deklarierten externen Funktion keine Nebeneffekte hat. Mit dieser Annotation kann der Compiler Aufrufe an die Funktion entfernen, wenn der Rückgabewert nicht verwendet wird. Die Annotation ist nur in extern files zulässig.

Beispiel:

/** @nosideeffects */
function noSideEffectsFn1() {}

/** @nosideeffects */
var noSideEffectsFn2 = function() {};

/** @nosideeffects */
a.prototype.noSideEffectsFn3 = function() {};

Gibt an, dass eine Methode oder Eigenschaft einer abgeleiteten Klasse absichtlich eine Methode oder Eigenschaft der übergeordneten Klasse ausgeblendet. Wenn keine anderen Annotationen enthalten sind, übernimmt die Methode oder Property automatisch Annotationen von der übergeordneten Klasse.

Beispiel:

/**
 * @return {string} Human-readable representation of
 *     project.SubClass.
 * @override
 */
project.SubClass.prototype.toString = function() {
  ...
};

Kennzeichnet ein Mitglied oder eine Property als privat. Nur Code im selben Verzeichnis kann auf Namen zugreifen, die als @package gekennzeichnet sind. Insbesondere kann Code in übergeordneten und untergeordneten Verzeichnissen nicht auf Namen zugreifen, die mit @package gekennzeichnet sind.

Öffentliche Konstruktoren können Attribute vom Typ @package haben, um die Methoden einzuschränken, die Aufrufer außerhalb des Verzeichnisses verwenden können. @package-Konstruktoren können jedoch öffentliche Attribute haben, um zu verhindern, dass Aufrufer außerhalb des Verzeichnisses einen Typ direkt instanziieren.

Beispiel:

/**
 * Returns the window object the foreign document resides in.
 *
 * @return {Object} The window object of the peer.
 * @package
 */
goog.net.xpc.CrossPageChannel.prototype.getPeerWindowObject = function() {
  // ...
};

Wird mit Methoden-, Funktions- und Konstruktordefinitionen zum Angeben der Arten von Funktionsargumenten verwendet. @param-Tags müssen in derselben Reihenfolge wie die Parameter in der Funktionsdefinition angegeben werden.

Auf das Tag @param muss ein Typausdruck folgen.

Alternativ können Sie die Parametertypen inline annotieren (siehe Beispiel foo).

Beispiel:

/**
 * Queries a Baz for items.
 * @param {number} groupNum Subgroup id to query.
 * @param {string|number|null} term An itemName,
 *     or itemId, or null to search everything.
 */
goog.Baz.prototype.query = function(groupNum, term) {
  ...
};

function foo(/** number */ a, /** number */ b) {
  return a - b + 1;
}

/**
 * @param {{name: string, age: number}} person
 */
function logPerson({name, age}) {
  console.log(`${name} is ${age} years old`);
}

Kennzeichnet ein Mitglied als privat. Nur Code in derselben Datei kann auf globale Variablen und Funktionen zugreifen, die als @private gekennzeichnet sind. Konstruktoren, die als @private gekennzeichnet sind, können nur durch Code in derselben Datei und durch ihre statischen und Instanzmitglieder instanziiert werden.

Auf die öffentlichen statischen Attribute von als @private gekennzeichneten Konstruktoren kann auch von überall aus zugegriffen werden. Der Operator instanceof kann immer auf @private-Mitglieder zugreifen.

Beispiel:

/**
 * Handlers that are listening to this logger.
 * @private {Array<Function>}
 */
this.handlers_ = [];

Gibt an, dass ein Mitglied oder eine Property geschützt ist.

Eine Property mit dem Label @protected kann aufgerufen werden:

• den gesamten Code in derselben Datei
• Statische Methoden und Instanzmethoden einer abgeleiteten Klasse der Klasse, für die das Attribut definiert ist.

Beispiel:

/**
 * Sets the component's root element to the given element.
 * Considered protected and final.
 * @param {Element} element Root element for the component.
 * @protected
 */
goog.ui.Component.prototype.setElementInternal = function(element) {
  // ...
};

Kennzeichnet eine Funktion als Strukturschnittstelle. Eine Strukturschnittstelle ähnelt einer nominalen @interface, ermöglicht jedoch implizite Implementierungen. Dies bedeutet, dass die Klasse in allen Klassen mit den Methoden und Eigenschaften implementiert wird, die im Prototoype der Strukturschnittstelle definiert sind, unabhängig davon, ob sie das Tag @implements verwendet. Datensatztypen und Objektliterale implementieren implizit auch eine strukturelle Schnittstelle, wenn sie die erforderlichen Attribute enthalten.

Beispiel:

/**
 * Anything with a draw() method.
 * @record
 */
function Drawable() {};
Drawable.prototype.draw = function() {};

/**
 * A polygon.
 * @param {!Drawable} x
 */
function render(x) { x.draw(); };

var o = { draw() { /* ... */ } };
render(o);

Gibt die Rückgabetypen von Methoden- und Funktionsdefinitionen an. Auf das Tag @return muss ein Typausdruck folgen.

Alternativ können Sie den Rückgabetyp inline angeben (siehe Beispiel foo).

Wenn eine Funktion, die nicht in extern enthalten ist, keinen Rückgabewert hat, können Sie das Tag @return weglassen. Der Compiler geht dann davon aus, dass die Funktion undefined zurückgibt.

Beispiel:

/**
 * Returns the ID of the last item.
 * @return {string} The hex ID.
 */
goog.Baz.prototype.getLastId = function() {
  ...
  return id;
};

function /** number */ foo(x) { return x - 1; }

Mit @struct werden Objekte mit einer festen Anzahl von Attributen erstellt. Wenn ein Konstruktor (im Beispiel Foo) mit @struct annotiert ist, können Sie nur die Punktnotation verwenden, um auf die Attribute von Foo-Objekten und nicht auf die eckige Klammer zuzugreifen. Außerdem können Sie einer Foo-Instanz nach ihrer Konstruktion kein Attribut hinzufügen. Die Annotation kann auch direkt für Objektliterale verwendet werden.

Beispiel:

/**
 * @constructor
 * @struct
 */
function Foo(x) {
  this.x = x;
}
var obj1 = new Foo(123);
var someVar = obj1.x;  // OK
obj1.x = "qwerty";  // OK
obj1['x'] = "asdf";  // warning
obj1.y = 5;  // warning

var obj2 = /** @struct */ { x: 321 };
obj2['x'] = 123;  // warning

Siehe Allgemeine Typen.

Beispiel:

/**
 * @param {T} t
 * @constructor
 * @template T
 */
Container = function(t) { ... };

Gibt den Objekttyp an, auf den das Keyword this innerhalb einer Funktion verweist. Auf das Tag @this muss ein Typausdruck folgen.

Um Compiler-Warnungen zu vermeiden, müssen Sie die Annotation @this immer verwenden, wenn this in einer Funktion erscheint, die weder ein Prototyp noch eine als @constructor gekennzeichnete Funktion ist.

Beispiel:

chat.RosterWidget.extern('getRosterElement',
    /**
     * Returns the roster widget element.
     * @this {Widget}
     * @return {Element}
     */
    function() {
      return this.getComponent().getElement();
    });

Wird verwendet, um die von einer Funktion ausgelösten Ausnahmen zu dokumentieren. Die Typprüfung verwendet diese Informationen derzeit nicht. Sie wird nur verwendet, um herauszufinden, ob eine in einer externen Datei deklarierte Funktion Nebeneffekte hat.

Beispiel:

/**
 * @throws {DOMException}
 */
DOMApplicationCache.prototype.swapCache = function() { ... };

Gibt den Typ einer Variablen, eines Attributs oder eines Ausdrucks an. Auf das Tag @type muss ein Typausdruck folgen.

Wenn Sie eine Variable oder einen Funktionsparameter deklarieren, können Sie die Typannotation wie im zweiten Beispiel inline weglassen und dabei {} und @type weglassen. Diese Tastenkombination kann nur verwendet werden, wenn eine Variable oder ein Funktionsparameter deklariert ist. Wenn Sie den Typ später anpassen möchten, benötigen Sie eine Umwandlung von Typ.

Beispiel:

/**
 * The message hex ID.
 * @type {string}
 */
var hexId = hexId;

var /** string */ name = 'Jamie';
function useSomething(/** (string|number|!Object) */ something) {
...
}

Gibt einen Alias für einen komplexeren Typ an. Derzeit können typedef-Elemente nur auf der obersten Ebene, nicht innerhalb von Funktionen, definiert werden. Wir haben diese Einschränkung in der neuen Inferenztyp behoben.

Beispiel:

/** @typedef {(string|number)} */
goog.NumberLike;

/** @param {goog.NumberLike} x A number or a string. */
goog.readNumber = function(x) {
  ...
}

Gibt an, dass eine Klasse weder vom Typ @struct noch vom Typ @dict ist. Dies ist die Standardeinstellung. Sie muss normalerweise nicht explizit geschrieben werden, es sei denn, Sie verwenden goog.defineClass oder das Schlüsselwort class, mit denen beide Klassen standardmäßig @structs sind.

Beispiel:

/**
 * @constructor
 * @unrestricted
 */
function Foo(x) {
  this.x = x;
}
var obj1 = new Foo(123);
var someVar = obj1.x;  // OK
obj1.x = "qwerty";  // OK
obj1['x'] = "asdf";  // OK
obj1.y = 5;  // OK