Contrassegna un metodo come astratto. Analogamente all'impostazione di un metodo su goog.abstractMethod, il compilatore può eliminare i metodi annotati con @abstract per ridurre le dimensioni del codice.

Il compilatore genera un avviso se un metodo contrassegnato con @abstract ha un'implementazione non vuota.

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

Contrassegna una variabile come di sola lettura. Il compilatore può incorporare variabili @const, in modo da ottimizzare il codice JavaScript.

La dichiarazione del tipo è facoltativa.

Il compilatore genera un avviso se a una variabile contrassegnata con @const viene assegnato un valore più di una volta. Se la variabile è un oggetto, tieni presente che il compilatore non vieta le modifiche alle proprietà dell'oggetto.

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

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

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

Contrassegna una funzione come costruttore. Il compilatore richiede un'annotazione @constructor per qualsiasi funzione utilizzata con la parola chiave new

Ad esempio:

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

Ad esempio:

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

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

Contrassegna una funzione, un metodo o una proprietà per fare in modo che, utilizzandola, venga generato un avviso del compilatore che indica che non deve più essere utilizzato.

Ad esempio:

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

@dict viene utilizzato per creare oggetti con un numero variabile di proprietà. Quando un costruttore (Foo nell'esempio) ha un'annotazione @dict, puoi utilizzare solo la notazione tra parentesi per accedere alle proprietà degli oggetti Foo. L'annotazione può essere usata anche direttamente nei valori letterali degli oggetti.

Ad esempio:

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

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

Specifica il tipo di un'enumerazione. Un'enumerazione è un oggetto le cui proprietà costituiscono un insieme di costanti correlate. Il tag @enum deve essere seguito da un'espressione di tipo.

L'etichetta del tipo di un'enumerazione si applica a ogni proprietà dell'enumerazione. Ad esempio, se un'enumerazione ha il tipo number, ogni proprietà enumerata deve essere un numero. Se il tipo di un'enumerazione viene omesso, viene usato il valore number.

Ad esempio:

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

Dato questo codice

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

Quando il compilatore viene eseguito con il flag --generate_exports, genera il codice:

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

che esporteranno i simboli nel codice non compilato. Puoi scrivere /** @export {SomeType} */ come abbreviazione di

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

Il codice che utilizza l'annotazione @export deve:

1. includi closure/base.js oppure
2. definiscono sia goog.exportSymbol che goog.exportProperty con la stessa firma di metodo nel proprio codebase.

Contrassegna una classe o un'interfaccia come ereditata da un'altra classe. Una classe contrassegnata con @extends deve essere contrassegnata anche con @constructor o @interface.

Nota: @extends non comporta l'ereditarietà di una classe da un'altra. L'annotazione indica semplicemente al compilatore di trattare una classe come sottoclasse di un'altra durante il controllo dei tipi.

Per un esempio di implementazione dell'ereditarietà, consulta la funzione Chiusura della libreria goog.inherits().

Ad esempio:

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

Indica che non è consentito estendere il corso. Per i metodi, indica che a nessuna sottoclasse è consentito sostituire quel metodo.

Ad esempio:

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

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

Utilizzato con @constructor per indicare che una classe implementa un'interfaccia.

Il compilatore genera un avviso se tagghi un costruttore con @implements e poi non riesci a implementare tutti i metodi e le proprietà definiti dall'interfaccia.

Ad esempio:

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

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

Questa annotazione può apparire solo nelle dichiarazioni delle proprietà esterne. La proprietà ha un tipo dichiarato, ma puoi assegnarle qualsiasi tipo senza avviso. Quando accedi alla proprietà, ti viene restituito un valore del tipo dichiarato. Ad esempio, puoi assegnare element.innerHTML a qualsiasi tipo, ma restituisce sempre una stringa.

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

Indica che un metodo o una proprietà di una sottoclasse nasconde di proposito un metodo o una proprietà di tale classe e ha esattamente la stessa documentazione. Tieni presente che il tag @inheritDoc implica il tag @override.

Ad esempio:

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

Contrassegna una funzione come interfaccia. Un'interfaccia specifica i membri obbligatori di un tipo. Qualsiasi classe che implementa un'interfaccia deve implementare tutti i metodi e le proprietà definiti nel prototipo dell'interfaccia. Consulta @implements.

Il compilatore verifica che non sia stata creata un'istanza delle interfacce. Se la parola chiave new viene utilizzata con una funzione di interfaccia, il compilatore genera un avviso.

Ad esempio:

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

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

Indica che le chiavi del valore letterale di un oggetto devono essere considerate come proprietà di un altro oggetto. Questa annotazione deve essere visualizzata solo nei valori letterali degli oggetti.

Tieni presente che il nome tra parentesi graffe non è un nome tipo come nelle altre annotazioni. È il nome di un oggetto. Denomina l'oggetto a cui vengono prestate le proprietà. Ad esempio, @type {Foo} significa "un'istanza di Foo", ma @lends {Foo} significa "il costruttore Foo".

Per ulteriori informazioni su questa annotazione, consulta la documentazione relativa a JSDoc.

Ad esempio:

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

Indica al compilatore di inserire il commento associato prima del codice compilato per il file contrassegnato. Questa annotazione consente di mantenere invariate le compilazioni di notifiche legali (come licenze legali o testo del copyright). Le interruzioni di riga vengono conservate.

Ad esempio:

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

Indica una proprietà che non deve essere compressa dal compilatore in una variabile. L'utilizzo principale di @nocollapse è consentire l'esportazione di proprietà modificabili. Tieni presente che le proprietà non compresse possono comunque essere rinominate dal compilatore. Se annotate una proprietà che è un oggetto con @nocollapse, tutte le sue proprietà rimarranno non compresse.

Ad esempio:

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

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

window['foobar'] = foo.bar;

Indica che una chiamata alla funzione esterna dichiarata non ha effetti collaterali. Questa annotazione consente al compilatore di rimuovere le chiamate alla funzione se il valore restituito non viene utilizzato. L'annotazione è consentita solo in extern files.

Ad esempio:

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

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

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

Indica che un metodo o una proprietà di una sottoclasse nasconde intenzionalmente un metodo o una proprietà della superclasse. Se non sono incluse altre annotazioni, il metodo o la proprietà ereditano automaticamente le annotazioni dalla relativa superclasse.

Ad esempio:

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

Contrassegna un membro o una proprietà come pacchetto privato. Solo il codice nella stessa directory può accedere ai nomi contrassegnati con @package. In particolare, il codice nelle directory padre e figlio non può accedere ai nomi contrassegnati con @package.

I costruttori pubblici possono avere proprietà @package per limitare i metodi che i chiamanti esterni alla directory possono utilizzare. D'altra parte, i costruttori @package possono avere proprietà pubbliche per impedire ai chiamanti esterni alla directory di creare un'istanza di un tipo direttamente.

Ad esempio:

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

Utilizzato con le definizioni di metodo, funzione e costruttore per specificare i tipi di argomenti della funzione. I tag @param devono essere nello stesso ordine dei parametri nella definizione della funzione.

Il tag @param deve essere seguito da un'espressione di tipo.

In alternativa, puoi annotare i tipi di parametri in linea (vedi la funzione foo nell'esempio).

Ad esempio:

/**
 * 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`);
}

Contrassegna un membro come privato. Solo il codice nello stesso file può accedere alle variabili e alle funzioni globali contrassegnate con @private. I costruttori contrassegnati come @private possono avere un'istanza solo per il codice nello stesso file e per i membri statici e di istanza.

Puoi accedere ovunque alle proprietà statiche pubbliche dei costruttori contrassegnate con @private, inoltre l'operatore instanceof può sempre accedere ai membri @private.

Ad esempio:

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

Indica che un membro o una proprietà sono protetti.

Una proprietà contrassegnata come @protected è accessibile da:

• tutto il codice nello stesso file
• I metodi statici e di istanza di qualsiasi sottoclasse della classe in cui è definita la proprietà.

Ad esempio:

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

Contrassegna una funzione come interfaccia strutturale. Un'interfaccia strutturale è simile a una @interface nominale, ma consente implementazioni implicite. Questo significa che qualsiasi classe che include i metodi e le proprietà definiti nel prototomo dell'interfaccia strutturale implementa l'interfaccia strutturale, indipendentemente dall'utilizzo o meno del tag @implements. I tipi di record e i valori letterali degli oggetti implementano anche implicitamente un'interfaccia strutturale se contengono le proprietà obbligatorie.

Ad esempio:

/**
 * 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);

Specifica i tipi di ritorno delle definizioni di metodo e funzione. Il tag @return deve essere seguito da un'espressione di tipo.

In alternativa, puoi annotare il tipo di ritorno incorporato (vedi la funzione foo nell'esempio).

Se una funzione che non è in uso non ha un valore restituito, puoi omettere il tag @return e il compilatore presume che la funzione restituisca undefined.

Ad esempio:

/**
 * 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; }

@struct viene utilizzato per creare oggetti con un numero fisso di proprietà. Quando un costruttore (Foo nell'esempio) ha @struct, puoi utilizzare solo la notazione a punti per accedere alle proprietà degli oggetti Foo, non alla notazione a parentesi. Inoltre, non puoi aggiungere una proprietà a un'istanza Foo dopo la creazione. L'annotazione può essere usata anche direttamente nei valori letterali degli oggetti.

Ad esempio:

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

Vedi Tipi generici.

Ad esempio:

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

Specifica il tipo di oggetto a cui fa riferimento la parola chiave this. Il tag @this deve essere seguito da un'espressione di tipo.

Per evitare avvisi del compilatore, devi utilizzare un'annotazione @this ogni volta che this appare in una funzione che non è un metodo prototipo né una funzione contrassegnata come @constructor.

Ad esempio:

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

Utilizzato per documentare le eccezioni generate da una funzione. Al momento il controllore del tipo non utilizza queste informazioni. Viene utilizzato solo per capire se una funzione dichiarata in un file di tipo esterno ha effetti collaterali.

Ad esempio:

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

Identifica il tipo di variabile, proprietà o espressione. Il tag @type deve essere seguito da un'espressione di tipo.

Quando dichiari una variabile o un parametro di funzione, puoi scrivere l'annotazione del tipo in linea omettendo {} e @type, come nel secondo esempio. Questa scorciatoia può essere eseguita solo quando una variabile o un parametro di funzione è dichiarato. Se vuoi regolare il tipo in un secondo momento, hai bisogno di una digitazione.

Ad esempio:

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

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

Dichiara un alias per un tipo più complesso. Al momento, typedefs può essere definito solo al livello superiore, non all'interno delle funzioni. Abbiamo corretto questo limite nell'inferenza del nuovo tipo.

Ad esempio:

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

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

Indica che una classe non è di tipo @struct, né @dict. Questa è l'impostazione predefinita, pertanto non è generalmente necessario scriverla in modo esplicito, a meno che non utilizzi goog.defineClass o la parola chiave class, che producono entrambe classi @struct per impostazione predefinita.

Ad esempio:

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