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 le variabili @const, il che ottimizza 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à in modo che il relativo utilizzo generi un avviso del compilatore che indica che non deve più essere utilizzata.

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) è annotato con @dict, puoi utilizzare solo la notazione tra parentesi per accedere alle proprietà degli oggetti Foo. L'annotazione può essere utilizzata anche direttamente sui 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 utilizzato 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, genererà il codice:

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

che esporterà 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 o
2. definisci sia goog.exportSymbol che goog.exportProperty con la stessa firma del 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 fa sì che un corso venga ereditato da un altro corso. L'annotazione indica semplicemente al compilatore che può trattare una classe come sottoclasse di un'altra durante il controllo dei tipi.

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

Ad esempio:

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

Indica che questo corso non può essere esteso. Per i metodi, indica che nessuna sottoclasse può eseguire l'override di 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 contrassegni un costruttore con @implements e poi non implementi 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ò essere visualizzata solo nelle dichiarazioni di proprietà esterne. La proprietà ha un tipo dichiarato, ma puoi assegnarle qualsiasi tipo senza ricevere un avviso. Quando accedi alla proprietà, ricevi un valore del tipo dichiarato. Ad esempio, element.innerHTML può essere assegnato a qualsiasi tipo, ma restituirà sempre una stringa.

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

Indica che un metodo o una proprietà di una sottoclasse nasconde intenzionalmente un metodo o una proprietà della superclasse 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. Vedi @implements.

Il compilatore verifica che le interfacce non vengano istanziate. 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 di un oggetto letterale devono essere trattate come proprietà di un altro oggetto. Questa annotazione deve essere visualizzata solo nei valori letterali oggetto.

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

La documentazione del toolkit JSDoc contiene ulteriori informazioni su questa annotazione.

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 note importanti (come licenze legali o testo del copyright) durante la compilazione. Le interruzioni di riga vengono mantenute.

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 annoti una proprietà che è un oggetto con @nocollapse, tutte le relative proprietà rimarranno espanse.

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à eredita automaticamente le annotazioni dalla superclasse.

Ad esempio:

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

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

I costruttori pubblici possono avere @package proprietà 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 direttamente un'istanza di un tipo.

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 definizioni di metodi, funzioni e costruttori 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 a variabili e funzioni globali contrassegnate con @private. I costruttori contrassegnati con @private possono essere istanziati solo dal codice nello stesso file e dai relativi membri statici e di istanza.

È possibile accedere ovunque anche alle proprietà statiche pubbliche dei costruttori contrassegnati con @private e 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à è protetto.

Una proprietà contrassegnata con @protected è accessibile a:

• tutto il codice nello stesso file
• metodi statici e metodi di istanza di qualsiasi sottoclasse della classe su 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 un tipo nominale @interface, ma consente implementazioni implicite. Ciò significa che qualsiasi classe che include i metodi e le proprietà definiti nel prototipo dell'interfaccia strutturale implementa l'interfaccia strutturale, indipendentemente dal fatto che utilizzi il tag @implements. Anche i tipi di record e i valori letterali degli oggetti implementano implicitamente un'interfaccia strutturale se contengono le proprietà richieste.

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 restituiti delle definizioni di metodi e funzioni. Il tag @return deve essere seguito da un'espressione di tipo.

In alternativa, puoi annotare il tipo restituito inline (vedi la funzione foo nell'esempio).

Se una funzione che non è in externs non ha un valore restituito, puoi omettere il tag @return e il compilatore presupporrà 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) è annotato con @struct, puoi utilizzare solo la notazione con il punto per accedere alle proprietà degli oggetti Foo, non la notazione con le parentesi. Inoltre, non puoi aggiungere una proprietà a un'istanza Foo dopo la sua creazione. L'annotazione può essere utilizzata anche direttamente sui 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 all'interno di una funzione. 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 viene visualizzato 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. Il controllo dei tipi non utilizza attualmente queste informazioni. Viene utilizzato solo per capire se una funzione dichiarata in un file externs 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 di tipo in linea omettendo {} e @type, come nel secondo esempio. Questa scorciatoia può essere utilizzata solo nei punti in cui viene dichiarata una variabile o un parametro di funzione. Se vuoi modificare il tipo in un secondo momento, avrai bisogno di un cast di tipo.

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, i typedef possono essere definiti solo a livello principale, non all'interno delle funzioni. Abbiamo corretto questa limitazione nella nuova inferenza dei tipi.

Ad esempio:

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

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

Indica che un corso non è di tipo @struct né di tipo @dict. Questa è l'impostazione predefinita, quindi in genere non è necessario scriverla esplicitamente, a meno che non utilizzi la parola chiave class, che produce classi che sono @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