Marca un método como abstracto. Al igual que cuando se configura un método como goog.abstractMethod, el compilador puede quitar los métodos anotados con @abstract para reducir el tamaño del código.

El compilador genera una advertencia si un método marcado con @abstract tiene una implementación no vacía.

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

Marca una variable como de solo lectura. El compilador puede insertar variables @const de forma intercalada, lo que optimiza el código JavaScript.

La declaración de tipo es opcional.

El compilador genera una advertencia si a una variable marcada con @const se le asigna un valor más de una vez. Si la variable es un objeto, ten en cuenta que el compilador no prohíbe los cambios en las propiedades del objeto.

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

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

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

Marca una función como constructor. El compilador requiere una anotación @constructor para cualquier función que se use con la palabra clave new.

Por ejemplo:

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

Por ejemplo:

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

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

Marca una función, un método o una propiedad para que su uso genere una advertencia del compilador que indique que ya no se debe usar.

Por ejemplo:

/**
 * 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 se usa para crear objetos con una cantidad variable de propiedades. Cuando un constructor (Foo en el ejemplo) se anota con @dict, solo puedes usar la notación de corchetes para acceder a las propiedades de los objetos Foo. La anotación también se puede usar directamente en literales de objetos.

Por ejemplo:

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

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

Especifica el tipo de enumeración. Un enum es un objeto cuyas propiedades constituyen un conjunto de constantes relacionadas. La etiqueta @enum debe ir seguida de una expresión de tipo.

La etiqueta de tipo de un enum se aplica a cada propiedad del enum. Por ejemplo, si un enum tiene el tipo number, cada una de sus propiedades enumeradas debe ser un número. Si se omite el tipo de una enumeración, se supone que es number.

Por ejemplo:

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

Dado este código

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

Cuando se ejecuta el compilador con la marca --generate_exports, se genera el siguiente código:

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

que exportará los símbolos al código sin compilar. Puedes escribir /** @export {SomeType} */ como abreviatura de

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

El código que usa la anotación @export debe cumplir con uno de los siguientes requisitos:

1. Incluye closure/base.js.
2. define goog.exportSymbol y goog.exportProperty con la misma firma de método en su propia base de código.

Marca una clase o interfaz como heredada de otra clase. Una clase marcada con @extends también debe estar marcada con @constructor o @interface.

Nota: @extends no hace que una clase herede de otra. La anotación simplemente le indica al compilador que puede tratar una clase como una subclase de otra durante la verificación de tipos.

Para ver un ejemplo de implementación de herencia, consulta la función de la biblioteca de Closure goog.inherits().

Por ejemplo:

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

Indica que no se permite extender esta clase. En el caso de los métodos, indica que ninguna subclase puede anular ese método.

Por ejemplo:

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

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

Se usa con @constructor para indicar que una clase implementa una interfaz.

El compilador genera una advertencia si etiquetas un constructor con @implements y, luego, no implementas todos los métodos y propiedades definidos por la interfaz.

Por ejemplo:

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

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

Esta anotación solo puede aparecer en declaraciones de propiedades externas. La propiedad tiene un tipo declarado, pero puedes asignarle cualquier tipo sin una advertencia. Cuando accedes a la propiedad, obtienes un valor del tipo declarado. Por ejemplo, a element.innerHTML se le puede asignar cualquier tipo, pero siempre devolverá una cadena.

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

Indica que un método o una propiedad de una subclase oculta intencionalmente un método o una propiedad de la superclase y tiene exactamente la misma documentación. Ten en cuenta que la etiqueta @inheritDoc implica la etiqueta @override.

Por ejemplo:

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

Marca una función como una interfaz. Una interfaz especifica los miembros requeridos de un tipo. Cualquier clase que implemente una interfaz debe implementar todos los métodos y las propiedades definidos en el prototipo de la interfaz. Consulta @implements.

El compilador verifica que no se creen instancias de las interfaces. Si la palabra clave new se usa con una función de interfaz, el compilador genera una advertencia.

Por ejemplo:

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

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

Indica que las claves de un literal de objeto se deben tratar como propiedades de algún otro objeto. Esta anotación solo debe aparecer en literales de objetos.

Observa que el nombre entre llaves no es un nombre de tipo como en otras anotaciones. Es un nombre de objeto. Nombra el objeto al que se prestan las propiedades. Por ejemplo, @type {Foo} significa "una instancia de Foo", pero @lends {Foo} significa "el constructor Foo".

En la documentación del kit de herramientas de JSDoc, encontrarás más información sobre esta anotación.

Por ejemplo:

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

Indica al compilador que inserte el comentario asociado antes del código compilado para el archivo marcado. Esta anotación permite que los avisos importantes (como las licencias legales o el texto de derechos de autor) sobrevivan a la compilación sin cambios. Se conservan los saltos de línea.

Por ejemplo:

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

Denota una propiedad que el compilador no debe contraer en una variable. El uso principal de @nocollapse es permitir la exportación de propiedades mutables. Ten en cuenta que el compilador puede cambiar el nombre de las propiedades no contraídas. Si anotas una propiedad que es un objeto con @nocollapse, todas sus propiedades también permanecerán sin contraer.

Por ejemplo:

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

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

window['foobar'] = foo.bar;

Indica que una llamada a la función externa declarada no tiene efectos secundarios. Esta anotación permite que el compilador quite las llamadas a la función si no se usa el valor de devolución. La anotación solo se permite en extern files.

Por ejemplo:

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

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

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

Indica que un método o una propiedad de una subclase oculta intencionalmente un método o una propiedad de la superclase. Si no se incluyen otras anotaciones, el método o la propiedad heredan automáticamente las anotaciones de su superclase.

Por ejemplo:

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

Marca un miembro o una propiedad como privados para el paquete. Solo el código del mismo directorio puede acceder a los nombres marcados como @package. En particular, el código de los directorios principal y secundario no puede acceder a los nombres marcados como @package.

Los constructores públicos pueden tener propiedades @package para restringir los métodos que pueden usar los llamadores fuera del directorio. Por otro lado, los constructores de @package pueden tener propiedades públicas para evitar que los llamadores fuera del directorio creen instancias de un tipo directamente.

Por ejemplo:

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

Se usa con definiciones de métodos, funciones y constructores para especificar los tipos de argumentos de funciones. Las etiquetas @param deben estar en el mismo orden que los parámetros en la definición de la función.

La etiqueta @param debe ir seguida de una expresión de tipo.

Como alternativa, puedes anotar los tipos de los parámetros de forma intercalada (consulta la función foo en el ejemplo).

Por ejemplo:

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

Marca a un miembro como privado. Solo el código del mismo archivo puede acceder a las variables y funciones globales marcadas como @private. Los constructores marcados como @private solo pueden instanciarse con código en el mismo archivo y con sus miembros estáticos y de instancia.

También se puede acceder a las propiedades estáticas públicas de los constructores marcados como @private en cualquier lugar, y el operador instanceof siempre puede acceder a los miembros @private.

Por ejemplo:

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

Indica que un miembro o una propiedad están protegidos.

Se puede acceder a una propiedad marcada como @protected de las siguientes maneras:

• Todo el código en el mismo archivo
• Métodos estáticos y métodos de instancia de cualquier subclase de la clase en la que se define la propiedad.

Por ejemplo:

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

Marca una función como una interfaz estructural. Una interfaz estructural es similar a una @interface nominal, pero permite implementaciones implícitas. Esto significa que cualquier clase que incluya los métodos y las propiedades definidos en el prototipo de la interfaz estructural implementa la interfaz estructural, ya sea que use o no la etiqueta @implements. Los tipos de registros y los literales de objetos también implementan de forma implícita una interfaz estructural si contienen las propiedades requeridas.

Por ejemplo:

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

Especifica los tipos de devolución de las definiciones de métodos y funciones. La etiqueta @return debe ir seguida de una expresión de tipo.

Como alternativa, puedes anotar el tipo de datos que se muestra de forma intercalada (consulta la función foo en el ejemplo).

Si una función que no está en externs no tiene un valor de devolución, puedes omitir la etiqueta @return, y el compilador supondrá que la función devuelve undefined.

Por ejemplo:

/**
 * 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 se usa para crear objetos con una cantidad fija de propiedades. Cuando un constructor (Foo en el ejemplo) se anota con @struct, solo puedes usar la notación de puntos para acceder a las propiedades de los objetos Foo, no la notación de corchetes. Además, no puedes agregar una propiedad a una instancia de Foo después de que se construye. La anotación también se puede usar directamente en literales de objetos.

Por ejemplo:

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

Consulta Tipos genéricos.

Por ejemplo:

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

Especifica el tipo del objeto al que hace referencia la palabra clave this dentro de una función. La etiqueta @this debe ir seguida de una expresión de tipo.

Para evitar advertencias del compilador, debes usar una anotación @this siempre que this aparezca en una función que no sea un método de prototipo ni una función marcada como @constructor.

Por ejemplo:

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

Se usa para documentar las excepciones que arroja una función. Actualmente, el verificador de tipos no usa esta información. Solo se usa para determinar si una función declarada en un archivo de externs tiene efectos secundarios.

Por ejemplo:

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

Identifica el tipo de una variable, propiedad o expresión. La etiqueta @type debe ir seguida de una expresión de tipo.

Cuando declaras un parámetro de función o variable, puedes escribir la anotación de tipo intercalada omitiendo {} y @type, como en el segundo ejemplo. Este atajo solo se puede realizar donde se declara un parámetro de variable o función. Si quieres ajustar el tipo más adelante, necesitarás una conversión de tipo.

Por ejemplo:

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

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

Declara un alias para un tipo más complejo. Actualmente, los typedefs solo se pueden definir en el nivel superior, no dentro de las funciones. Corregimos esta limitación en la nueva inferencia de tipos.

Por ejemplo:

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

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

Indica que una clase no es de tipo @struct ni de tipo @dict. Este es el valor predeterminado, por lo que, en general, no es necesario escribirlo de forma explícita, a menos que uses la palabra clave class, que produce clases que son @structs de forma predeterminada.

Por ejemplo:

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