Marca um método como abstrato. Assim como ao definir um método como goog.abstractMethod, o compilador pode remover métodos anotados com @abstract para reduzir o tamanho do código.

O compilador gera um aviso se um método marcado com @abstract tiver uma implementação não vazia.

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

Marca uma variável como somente leitura. O compilador pode inserir variáveis @const, o que otimiza o código JavaScript.

A declaração de tipo é opcional.

O compilador gera um aviso se uma variável marcada com @const receber um valor mais de uma vez. Se a variável for um objeto, o compilador não vai impedir mudanças nas propriedades dele.

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

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

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

Marca uma função como um construtor. O compilador exige uma anotação @constructor para qualquer função usada com a palavra-chave new.

Exemplo:

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

Exemplo:

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

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

Marca uma função, um método ou uma propriedade para que o uso dela produza um aviso do compilador indicando que ela não deve mais ser usada.

Exemplo:

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

O @dict é usado para criar objetos com um número variável de propriedades. Quando um construtor (Foo no exemplo) é anotado com @dict, só é possível usar a notação de colchetes para acessar as propriedades de objetos Foo. A anotação também pode ser usada diretamente em literais de objeto.

Exemplo:

/**
 * @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 o tipo de uma enumeração. Uma enumeração é um objeto cujas propriedades constituem um conjunto de constantes relacionadas. A tag @enum precisa ser seguida por uma expressão de tipo.

O rótulo de tipo de uma enumeração se aplica a cada propriedade dela. Por exemplo, se uma enumeração tiver o tipo number, cada uma das propriedades enumeradas precisará ser um número. Se o tipo de uma enumeração for omitido, number será presumido.

Exemplo:

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

Quando o compilador é executado com a flag --generate_exports, ele gera o código:

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

que vai exportar os símbolos para o código não compilado. Você pode escrever /** @export {SomeType} */ como uma abreviação de

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

O código que usa a anotação @export precisa

1. incluir closure/base.js ou
2. defina goog.exportSymbol e goog.exportProperty com a mesma assinatura de método na própria base de código.

Marca uma classe ou interface como herdeira de outra classe. Uma classe marcada com @extends também precisa ser marcada com @constructor ou @interface.

Observação: @extends não faz com que uma classe herde de outra. A anotação simplesmente informa ao compilador que ele pode tratar uma classe como uma subclasse de outra durante a verificação de tipos.

Para um exemplo de implementação de herança, consulte a função da biblioteca Closure goog.inherits().

Exemplo:

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

Indica que essa classe não pode ser estendida. Para métodos, indica que nenhuma subclasse pode substituir esse método.

Exemplo:

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

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

Usado com @constructor para indicar que uma classe implementa uma interface.

O compilador gera um aviso se você marcar um construtor com @implements e não implementar todos os métodos e propriedades definidos pela interface.

Exemplo:

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

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

Essa anotação só pode aparecer em declarações de propriedades externas. A propriedade tem um tipo declarado, mas você pode atribuir qualquer tipo a ela sem um aviso. Ao acessar a propriedade, você recebe um valor do tipo declarado. Por exemplo, element.innerHTML pode receber qualquer tipo, mas sempre vai retornar uma string.

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

Indica que um método ou propriedade de uma subclasse oculta intencionalmente um método ou propriedade da superclasse e tem exatamente a mesma documentação. A tag @inheritDoc implica a tag @override.

Exemplo:

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

Marca uma função como uma interface. Uma interface especifica os membros obrigatórios de um tipo. Qualquer classe que implemente uma interface precisa implementar todos os métodos e propriedades definidos no protótipo da interface. Veja @implements.

O compilador verifica se as interfaces não são instanciadas. Se a palavra-chave new for usada com uma função de interface, o compilador vai gerar um aviso.

Exemplo:

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

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

Indica que as chaves de um literal de objeto devem ser tratadas como propriedades de algum outro objeto. Essa anotação só deve aparecer em literais de objeto.

O nome entre chaves não é um nome de tipo como em outras anotações. É um nome de objeto. Ele nomeia o objeto a que as propriedades são emprestadas. Por exemplo, @type {Foo} significa "uma instância de Foo", mas @lends {Foo} significa "o construtor Foo".

A documentação do JSDoc Toolkit tem mais informações sobre essa anotação.

Exemplo:

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

Instrui o compilador a inserir o comentário associado antes do código compilado do arquivo marcado. Essa anotação permite que avisos importantes (como licenças legais ou texto de direitos autorais) sobrevivam à compilação sem alterações. As quebras de linha são preservadas.

Exemplo:

/**
 * @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 uma propriedade que não deve ser recolhida pelo compilador em uma variável. O principal uso de @nocollapse é permitir a exportação de propriedades mutáveis. As propriedades não recolhidas ainda podem ser renomeadas pelo compilador. Se você anotar uma propriedade que é um objeto com @nocollapse, todas as propriedades dela também vão permanecer não recolhidas.

Exemplo:

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

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

window['foobar'] = foo.bar;

Indica que uma chamada para a função externa declarada não tem efeitos colaterais. Essa anotação permite que o compilador remova chamadas para a função se o valor de retorno não for usado. A anotação só é permitida em extern files.

Exemplo:

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

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

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

Indica que um método ou propriedade de uma subclasse oculta intencionalmente um método ou propriedade da superclasse. Se nenhuma outra anotação for incluída, o método ou a propriedade vai herdar automaticamente as anotações da superclasse.

Exemplo:

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

Marca um membro ou propriedade como pacote particular. Apenas o código no mesmo diretório pode acessar nomes marcados como @package. Em especial, o código nos diretórios pai e filho não pode acessar nomes marcados como @package.

Os construtores públicos podem ter propriedades @package para restringir os métodos que os chamadores fora do diretório podem usar. Por outro lado, os construtores @package podem ter propriedades públicas para impedir que chamadores fora do diretório instanciem diretamente um tipo.

Exemplo:

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

Usado com definições de método, função e construtor para especificar os tipos de argumentos de função. As tags @param precisam estar na mesma ordem dos parâmetros na definição da função.

A tag @param precisa ser seguida por uma expressão de tipo.

Como alternativa, você pode anotar os tipos dos parâmetros inline (consulte a função foo no exemplo).

Exemplo:

/**
 * 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 um membro como particular. Apenas o código no mesmo arquivo pode acessar variáveis e funções globais marcadas como @private. Os construtores marcados com @private só podem ser instanciados por código no mesmo arquivo e pelos membros estáticos e de instância.

As propriedades estáticas públicas de construtores marcados como @private também podem ser acessadas em qualquer lugar, e o operador instanceof sempre pode acessar membros @private.

Exemplo:

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

Indica que um membro ou uma propriedade está protegida.

Uma propriedade marcada como @protected pode ser acessada por:

• todo o código no mesmo arquivo
• métodos estáticos e de instância de qualquer subclasse da classe em que a propriedade é definida.

Exemplo:

/**
 * 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 uma função como uma interface estrutural. Uma interface estrutural é semelhante a uma @interface nominal, mas permite implementações implícitas. Isso significa que qualquer classe que inclua os métodos e propriedades definidos no protótipo da interface estrutural implementa a interface estrutural, usando ou não a tag @implements. Tipos de registro e literais de objeto também implementam implicitamente uma interface estrutural se contiverem as propriedades necessárias.

Exemplo:

/**
 * 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 os tipos de retorno de definições de método e função. A tag @return precisa ser seguida por uma expressão de tipo.

Como alternativa, você pode anotar o tipo de retorno inline (consulte a função foo no exemplo).

Se uma função que não está em externs não tiver um valor de retorno, omita a tag @return. O compilador vai presumir que a função retorna undefined.

Exemplo:

/**
 * 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 é usado para criar objetos com um número fixo de propriedades. Quando um construtor (Foo no exemplo) é anotado com @struct, só é possível usar a notação de ponto para acessar as propriedades de objetos Foo, não a notação de colchetes. Além disso, não é possível adicionar uma propriedade a uma instância Foo depois que ela é criada. A anotação também pode ser usada diretamente em literais de objeto.

Exemplo:

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

Consulte Tipos genéricos.

Exemplo:

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

Especifica o tipo do objeto a que a palavra-chave this se refere em uma função. A tag @this precisa ser seguida por uma expressão de tipo.

Para evitar avisos do compilador, use uma anotação @this sempre que this aparecer em uma função que não seja um método de protótipo nem uma função marcada como @constructor.

Exemplo:

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

Usado para documentar as exceções geradas por uma função. No momento, o verificador de tipos não usa essas informações. Ele só é usado para descobrir se uma função declarada em um arquivo de externs tem efeitos colaterais.

Exemplo:

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

Identifica o tipo de uma variável, propriedade ou expressão. A tag @type precisa ser seguida por uma expressão de tipo.

Ao declarar uma variável ou um parâmetro de função, é possível escrever a anotação de tipo inline omitindo {} e @type, como no segundo exemplo. Esse atalho só pode ser usado quando uma variável ou um parâmetro de função é declarado. Se você quiser ajustar o tipo depois, vai precisar de uma conversão de tipo.

Exemplo:

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

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

Declara um alias para um tipo mais complexo. No momento, os typedefs só podem ser definidos no nível superior, não dentro de funções. Corrigimos essa limitação na nova inferência de tipo.

Exemplo:

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

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

Indica que uma classe não é um tipo @struct nem @dict. Esse é o padrão, então geralmente não é necessário escrever explicitamente, a menos que você esteja usando a palavra-chave class, que produz classes @struct por padrão.

Exemplo:

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