Marque une méthode comme abstraite. À l'instar de la définition d'une méthode sur goog.abstractMethod, le compilateur peut éliminer des méthodes annotées avec @abstract pour réduire la taille du code.

Le compilateur génère un avertissement si une méthode marquée avec @abstract a une implémentation non vide.

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

Marque une variable comme étant en lecture seule. Le compilateur peut intégrer des variables @const, ce qui optimise le code JavaScript.

La déclaration du type est facultative.

Le compilateur génère un avertissement si une valeur est attribuée à une variable plusieurs fois avec @const. Si la variable est un objet, notez que le compilateur n'interdit pas de modifier les propriétés de l'objet.

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

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

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

Marque une fonction en tant que constructeur. Le compilateur nécessite une annotation @constructor pour toute fonction utilisée avec le mot clé new.

Exemple :

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

Exemple :

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

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

Marque une fonction, une méthode ou une propriété de sorte que son utilisation génère un avertissement du compilateur indiquant qu'elle ne doit plus être utilisée.

Exemple :

/**
 * 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 permet de créer des objets avec un nombre variable de propriétés. Lorsqu'un constructeur (Foo dans l'exemple) est annoté avec @dict, vous ne pouvez utiliser que la notation entre crochets pour accéder aux propriétés des objets Foo. L'annotation peut également être utilisée directement sur des littéraux d'objet.

Exemple :

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

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

Spécifie le type d'énumération. Une énumération est un objet dont les propriétés constituent un ensemble de constantes associées. Le tag @enum doit être suivi d'une expression de type.

Le libellé de type d'une énumération s'applique à chaque propriété de l'énumération. Par exemple, si une énumération est de type number, chacune de ses propriétés énumérées doit être un nombre. Si le type d'une énumération est omis, la valeur number est déduite par défaut.

Exemple :

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

Avec ce code

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

Lorsque le compilateur est exécuté avec l'option --generate_exports, il génère le code suivant:

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

qui exportera les symboles vers du code non compilé. Vous pouvez écrire /** @export {SomeType} */ en tant que raccourci pour

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

Le code qui utilise l'annotation @export doit soit

1. inclure closure/base.js ou
2. définir à la fois goog.exportSymbol et goog.exportProperty avec la même signature de méthode dans leur propre codebase ;

Marque une classe ou une interface comme héritant d'une autre classe. Une classe marquée avec @extends doit également être marquée avec @constructor ou @interface.

Remarque : @extends n'entraîne pas l'héritage d'une classe à partir d'une autre classe. L'annotation indique simplement au compilateur qu'il peut traiter une classe comme une sous-classe d'une autre pendant la vérification du type.

Pour obtenir un exemple de mise en œuvre de l'héritage, consultez la page sur la fonction Closure Librarygoog.inherits().

Exemple :

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

Indique que cette classe ne peut pas être étendue. Pour les méthodes, indique qu'aucune sous-classe n'est autorisée à remplacer cette méthode.

Exemple :

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

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

Utilisé avec @constructor pour indiquer qu'une classe implémente une interface.

Le compilateur génère un avertissement si vous taguez un constructeur à l'aide de @implements, puis ne parvenez pas à implémenter toutes les méthodes et propriétés définies par l'interface.

Exemple :

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

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

Cette annotation ne peut apparaître que dans des déclarations de propriété externes. La propriété possède un type déclaré, mais vous pouvez lui attribuer n'importe quel type sans avertissement. Lorsque vous accédez à la propriété, vous obtenez une valeur du type déclaré. Par exemple, element.innerHTML peut être attribué à n'importe quel type, mais renvoie toujours une chaîne.

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

Indique qu'une méthode ou une propriété d'une sous-classe masque intentionnellement une méthode ou une propriété de la super-classe et qu'elle contient exactement la même documentation. Notez que le tag @inheritDoc implique le tag @override.

Exemple :

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

Marque une fonction en tant qu'interface. Une interface spécifie les membres requis d'un type. Toute classe qui implémente une interface doit implémenter toutes les méthodes et propriétés définies sur le prototype de l'interface. Consultez @implements.

Le compilateur vérifie que les interfaces ne sont pas instanciées. Si le mot clé new est utilisé avec une fonction d'interface, le compilateur génère un avertissement.

Exemple :

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

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

Indique que les clés d'un littéral d'objet doivent être traitées comme les propriétés d'un autre objet. Cette annotation ne doit apparaître que sur les littéraux d'objet.

Notez que le nom entre accolades ne correspond pas à un nom de type comme dans les autres annotations. Il s'agit d'un nom d'objet. Elle nomme l'objet auquel les propriétés sont prêtées. Par exemple, @type {Foo} signifie "une instance de Foo", tandis que @lends {Foo} signifie "le constructeur Foo".

La documentation du kit JSDoc contient plus d'informations sur cette annotation.

Exemple :

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

Indique au compilateur d'insérer le commentaire associé avant le code compilé pour le fichier marqué. Cette annotation permet aux avis importants (tels que les licences légales ou le texte de droits d'auteur) de rester inchangés. Les sauts de ligne sont conservés.

Exemple :

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

Indique une propriété qui ne doit pas être réduite par le compilateur en une variable. La principale utilisation de @nocollapse consiste à autoriser l'exportation de propriétés modifiables. Notez que le compilateur peut renommer les propriétés non réduites. Si vous annotez une propriété qui est un objet avec @nocollapse, toutes ses propriétés resteront également non réduites.

Exemple :

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

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

window['foobar'] = foo.bar;

Indique qu'un appel à la fonction externe déclarée n'a aucun effet secondaire. Cette annotation permet au compilateur de supprimer les appels à la fonction si la valeur de retour n'est pas utilisée. L'annotation n'est autorisée que dans extern files.

Exemple :

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

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

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

Indique qu'une méthode ou une propriété d'une sous-classe masque intentionnellement une méthode ou une propriété de la super-classe. Si aucune autre annotation n'est incluse, la méthode ou la propriété hérite automatiquement des annotations de sa super-classe.

Exemple :

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

Marque un membre ou une propriété comme privé. Seul le code du même répertoire peut accéder aux noms marqués @package. En particulier, le code des répertoires parent et enfant ne peut pas accéder aux noms marqués @package.

Les constructeurs publics peuvent disposer de propriétés @package pour restreindre les méthodes que les appelants externes à l'annuaire peuvent utiliser. En revanche, les constructeurs @package peuvent disposer de propriétés publiques pour empêcher les appelants en dehors du répertoire d'instancier directement un type.

Exemple :

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

Utilisé avec les définitions de méthode, de fonction et de constructeur pour spécifier les types d'arguments de la fonction. Les tags @param doivent être dans le même ordre que les paramètres de la définition de la fonction.

Le tag @param doit être suivi d'une expression de type.

Vous pouvez également annoter les types de paramètres intégrés (voir la fonction foo dans l'exemple).

Exemple :

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

Marque un membre comme privé. Seul le code du même fichier peut accéder aux fonctions et variables globales marquées @private. Les constructeurs marqués @private ne peuvent être instanciés que par du code contenu dans le même fichier, ainsi que par leurs membres statiques et ceux de l'instance.

Les propriétés statiques publiques des constructeurs marqués comme @private sont également accessibles partout, et l'opérateur instanceof peut toujours accéder aux membres @private.

Exemple :

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

Indique qu'un membre ou une propriété est protégé.

Une propriété marquée comme @protected est accessible à:

• tout le code du même fichier
• les méthodes statiques et les méthodes d'instance de toute sous-classe de la classe sur laquelle la propriété est définie.

Exemple :

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

Marque une fonction comme une interface structurelle. Une interface structurelle est semblable à une @interface nominale, mais elle permet des mises en œuvre implicites. Cela signifie que toute classe incluant les méthodes et propriétés définies dans le prototype de l'interface structurelle met en œuvre l'interface structurelle, qu'elle utilise ou non le tag @implements. Les types d'enregistrements et les littéraux d'objet mettent également en œuvre implicitement une interface structurelle s'ils contiennent les propriétés requises.

Exemple :

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

Spécifie les types de renvoi des définitions de méthode et de fonction. Le tag @return doit être suivi d'une expression de type.

Vous pouvez également annoter le type de retour intégré (voir la fonction foo dans l'exemple).

Si une fonction qui n'est pas dans des externs n'a pas de valeur renvoyée, vous pouvez omettre le tag @return. Le compilateur supposera alors que la fonction renvoie undefined.

Exemple :

/**
 * 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 permet de créer des objets avec un nombre fixe de propriétés. Lorsqu'un constructeur (Foo dans l'exemple) est annoté avec @struct, vous ne pouvez utiliser que la notation par points pour accéder aux propriétés des objets Foo, et non à la notation entre crochets. Vous ne pouvez pas non plus ajouter une propriété à une instance Foo après sa construction. L'annotation peut également être utilisée directement sur des littéraux d'objet.

Exemple :

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

Consultez Types génériques.

Exemple :

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

Spécifie le type d'objet auquel le mot clé this fait référence dans une fonction. Le tag @this doit être suivi d'une expression de type.

Pour éviter les avertissements du compilateur, vous devez utiliser une annotation @this chaque fois que this apparaît dans une fonction qui n'est ni une méthode de prototype, ni une fonction marquée comme @constructor.

Exemple :

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

Utilisée pour documenter les exceptions générées par une fonction. L'outil de vérification des types n'utilise pas ces informations pour le moment. Elle ne sert qu'à déterminer si une fonction déclarée dans un fichier externe a des effets secondaires.

Exemple :

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

Identifie le type d'une variable, d'une propriété ou d'une expression. Le tag @type doit être suivi d'une expression de type.

Lorsque vous déclarez un paramètre de variable ou de fonction, vous pouvez écrire l'annotation de type de façon intégrée en omettant {} et @type, comme dans le deuxième exemple. Ce raccourci ne peut être effectué que lorsqu'une variable ou un paramètre de fonction est déclaré. Si vous souhaitez ajuster le type plus tard, vous aurez besoin d'une cast type.

Exemple :

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

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

Déclare un alias pour un type plus complexe. Actuellement, les types de définition ne peuvent être définis qu'au niveau supérieur, et non à l'intérieur des fonctions. Nous avons corrigé cette limite dans l'inférence de nouveau type.

Exemple :

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

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

Indique qu'une classe n'est ni de type @struct, ni de type @dict. Il s'agit du format par défaut. Il n'est donc généralement pas nécessaire de l'écrire explicitement, sauf si vous utilisez goog.defineClass ou le mot clé class, qui produisent tous deux des classes qui sont des @struct par défaut.

Exemple :

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