Đánh dấu một phương thức là trừu tượng. Tương tự như việc đặt một phương thức thành goog.abstractMethod, trình biên dịch có thể cắt tỉa các phương thức được chú thích bằng @abstract để giảm kích thước mã.

Trình biên dịch sẽ tạo cảnh báo nếu một phương thức được đánh dấu bằng @abstract có một triển khai không trống.

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

Đánh dấu một biến là chỉ đọc. Trình biên dịch có thể nội tuyến các biến @const, giúp tối ưu hoá mã JavaScript.

Bạn không bắt buộc phải khai báo loại.

Trình biên dịch sẽ tạo cảnh báo nếu một biến được đánh dấu bằng @const được gán giá trị nhiều lần. Nếu biến là một đối tượng, hãy lưu ý rằng trình biên dịch không cấm các thay đổi đối với thuộc tính của đối tượng.

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

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

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

Đánh dấu một hàm là hàm khởi tạo. Trình biên dịch yêu cầu chú giải @constructor cho mọi hàm được dùng với từ khoá new

Ví dụ:

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

Ví dụ:

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

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

Đánh dấu một hàm, phương thức hoặc thuộc tính để việc sử dụng hàm, phương thức hoặc thuộc tính đó sẽ tạo ra cảnh báo của trình biên dịch cho biết rằng bạn không nên sử dụng hàm, phương thức hoặc thuộc tính đó nữa.

Ví dụ:

/**
 * 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 được dùng để tạo các đối tượng có số lượng thuộc tính thay đổi. Khi một hàm dựng (Foo trong ví dụ) được chú thích bằng @dict, bạn chỉ có thể sử dụng ký hiệu dấu ngoặc vuông để truy cập vào các thuộc tính của đối tượng Foo. Bạn cũng có thể sử dụng chú thích trực tiếp trên các chữ đối tượng.

Ví dụ:

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

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

Chỉ định loại của một enum. Enum là một đối tượng có các thuộc tính tạo thành một tập hợp các hằng số có liên quan. Thẻ @enum phải đứng sau một biểu thức loại.

Nhãn loại của một enum áp dụng cho từng thuộc tính của enum. Ví dụ: nếu một enum có loại number, thì mỗi thuộc tính được liệt kê của enum đó phải là một số. Nếu bạn bỏ qua loại của một enum, thì number sẽ được giả định.

Ví dụ:

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

Với đoạn mã này

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

khi trình biên dịch chạy với cờ --generate_exports, trình biên dịch sẽ tạo mã:

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

thao tác này sẽ xuất các biểu tượng sang mã chưa biên dịch. Bạn có thể viết /** @export {SomeType} */ thay cho

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

Mã sử dụng chú thích @export phải

1. bao gồm closure/base.js hoặc
2. xác định cả goog.exportSymbol và goog.exportProperty bằng cùng một chữ ký phương thức trong cơ sở mã riêng của chúng.

Đánh dấu một lớp hoặc giao diện là kế thừa từ một lớp khác. Một lớp được đánh dấu bằng @extends cũng phải được đánh dấu bằng @constructor hoặc @interface.

Lưu ý: @extends không khiến một lớp kế thừa từ một lớp khác. Chú thích này chỉ cho trình biên dịch biết rằng nó có thể coi một lớp là lớp con của một lớp khác trong quá trình kiểm tra kiểu.

Để xem ví dụ về cách triển khai tính kế thừa, hãy xem hàm Thư viện Closure goog.inherits().

Ví dụ:

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

Cho biết rằng bạn không được phép mở rộng lớp này. Đối với các phương thức, cho biết rằng không có lớp con nào được phép ghi đè phương thức đó.

Ví dụ:

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

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

Được dùng với @constructor để cho biết một lớp triển khai một giao diện.

Trình biên dịch sẽ đưa ra cảnh báo nếu bạn gắn thẻ một hàm khởi tạo bằng @implements rồi không triển khai tất cả các phương thức và thuộc tính do giao diện xác định.

Ví dụ:

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

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

Chú thích này chỉ có thể xuất hiện trong các khai báo thuộc tính bên ngoài. Thuộc tính có một loại được khai báo, nhưng bạn có thể chỉ định bất kỳ loại nào cho thuộc tính đó mà không có cảnh báo. Khi truy cập vào thuộc tính, bạn sẽ nhận lại được một giá trị thuộc loại đã khai báo. Ví dụ: element.innerHTML có thể được chỉ định bất kỳ loại nào, nhưng sẽ luôn trả về một chuỗi.

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

Cho biết rằng một phương thức hoặc thuộc tính của lớp con cố tình ẩn một phương thức hoặc thuộc tính của lớp cấp cao và có tài liệu hoàn toàn giống nhau. Xin lưu ý rằng thẻ @inheritDoc ngụ ý thẻ @override.

Ví dụ:

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

Đánh dấu một hàm là giao diện. Giao diện chỉ định các thành viên bắt buộc của một loại. Mọi lớp triển khai một giao diện đều phải triển khai tất cả các phương thức và thuộc tính được xác định trên nguyên mẫu của giao diện. Hãy xem @implements.

Trình biên dịch xác minh rằng các giao diện không được khởi tạo. Nếu từ khoá new được dùng với một hàm giao diện, trình biên dịch sẽ đưa ra cảnh báo.

Ví dụ:

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

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

Cho biết rằng các khoá của một đối tượng chữ cần được coi là thuộc tính của một số đối tượng khác. Chú thích này chỉ xuất hiện trên các giá trị cố định của đối tượng.

Lưu ý rằng tên trong dấu ngoặc nhọn không phải là tên loại như trong các chú thích khác. Đây là tên đối tượng. Nó đặt tên cho đối tượng mà các thuộc tính được cho mượn. Ví dụ: @type {Foo} có nghĩa là "một thực thể của Foo", nhưng @lends {Foo} có nghĩa là "hàm khởi tạo Foo".

Tài liệu về Bộ công cụ JSDoc có thêm thông tin về chú thích này.

Ví dụ:

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

Yêu cầu trình biên dịch chèn nhận xét được liên kết trước mã đã biên dịch cho tệp được đánh dấu. Chú thích này cho phép các thông báo quan trọng (chẳng hạn như giấy phép pháp lý hoặc văn bản bản quyền) tồn tại mà không thay đổi trong quá trình biên dịch. Dấu ngắt dòng được giữ nguyên.

Ví dụ:

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

Biểu thị một thuộc tính mà trình biên dịch không được thu gọn thành một biến. Mục đích chính của @nocollapse là cho phép xuất các thuộc tính có thể thay đổi. Xin lưu ý rằng trình biên dịch vẫn có thể đổi tên các thuộc tính không được thu gọn. Nếu bạn chú thích một thuộc tính là đối tượng bằng @nocollapse, thì tất cả các thuộc tính của đối tượng đó cũng sẽ vẫn không bị thu gọn.

Ví dụ:

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

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

window['foobar'] = foo.bar;

Cho biết rằng lệnh gọi đến hàm bên ngoài đã khai báo không có tác dụng phụ. Chú giải này cho phép trình biên dịch xoá các lệnh gọi đến hàm nếu giá trị trả về không được dùng. Bạn chỉ được phép sử dụng chú thích trong extern files.

Ví dụ:

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

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

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

Cho biết rằng một phương thức hoặc thuộc tính của lớp con cố tình ẩn một phương thức hoặc thuộc tính của lớp cấp cao. Nếu không có chú thích nào khác, phương thức hoặc thuộc tính sẽ tự động kế thừa chú thích từ lớp cấp cao.

Ví dụ:

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

Đánh dấu một thành viên hoặc thuộc tính là riêng tư theo gói. Chỉ mã trong cùng một thư mục mới có thể truy cập vào các tên được đánh dấu @package. Cụ thể, mã trong thư mục mẹ và thư mục con không thể truy cập vào các tên được đánh dấu @package.

Các hàm khởi tạo công khai có thể có các thuộc tính @package để hạn chế các phương thức mà người gọi bên ngoài thư mục có thể sử dụng. Mặt khác, các hàm khởi tạo @package có thể có các thuộc tính công khai để ngăn người gọi bên ngoài thư mục trực tiếp khởi tạo một kiểu.

Ví dụ:

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

Được dùng với các định nghĩa về phương thức, hàm và hàm khởi tạo để chỉ định các loại đối số của hàm. Thẻ @param phải theo cùng thứ tự với các tham số trong định nghĩa hàm.

Thẻ @param phải được theo sau bởi một biểu thức loại.

Ngoài ra, bạn có thể chú giải các loại tham số nội tuyến (xem hàm foo trong ví dụ).

Ví dụ:

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

Đánh dấu một thành viên là riêng tư. Chỉ mã trong cùng một tệp mới có thể truy cập vào các biến và hàm chung được đánh dấu @private. Chỉ mã trong cùng một tệp và các thành viên tĩnh và thành viên phiên bản của chúng mới có thể tạo thực thể cho các hàm khởi tạo được đánh dấu @private.

Bạn cũng có thể truy cập vào các thuộc tính tĩnh công khai của hàm khởi tạo được đánh dấu @private ở bất cứ đâu và toán tử instanceof luôn có thể truy cập vào các thành phần @private.

Ví dụ:

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

Cho biết rằng một thành phần hoặc thuộc tính được bảo vệ.

Một tài sản được đánh dấu @protected có thể truy cập vào:

• tất cả mã trong cùng một tệp
• các phương thức tĩnh và phương thức thực thể của mọi lớp con của lớp mà thuộc tính được xác định.

Ví dụ:

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

Đánh dấu một hàm là giao diện cấu trúc. Giao diện cấu trúc tương tự như @interface danh nghĩa, nhưng cho phép triển khai ngầm. Điều này có nghĩa là bất kỳ lớp nào bao gồm các phương thức và thuộc tính được xác định trên nguyên mẫu của giao diện cấu trúc đều triển khai giao diện cấu trúc, cho dù lớp đó có sử dụng thẻ @implements hay không. Các loại bản ghi và chữ số đối tượng cũng ngầm triển khai một giao diện cấu trúc nếu chúng chứa các thuộc tính bắt buộc.

Ví dụ:

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

Chỉ định kiểu trả về của các định nghĩa về phương thức và hàm. Thẻ @return phải được theo sau bởi một biểu thức loại.

Ngoài ra, bạn có thể chú thích kiểu dữ liệu trả về nội tuyến (xem hàm foo trong ví dụ).

Nếu một hàm không có trong externs không có giá trị trả về, bạn có thể bỏ qua thẻ @return và trình biên dịch sẽ giả định rằng hàm trả về undefined.

Ví dụ:

/**
 * 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 được dùng để tạo các đối tượng có số lượng thuộc tính cố định. Khi một hàm dựng (Foo trong ví dụ) được chú thích bằng @struct, bạn chỉ có thể sử dụng ký hiệu dấu chấm để truy cập vào các thuộc tính của đối tượng Foo, chứ không thể sử dụng ký hiệu dấu ngoặc vuông. Ngoài ra, bạn không thể thêm một thuộc tính vào một thực thể Foo sau khi thực thể đó được tạo. Bạn cũng có thể sử dụng chú thích trực tiếp trên các chữ đối tượng.

Ví dụ:

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

Xem phần Loại chung.

Ví dụ:

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

Chỉ định loại đối tượng mà từ khoá this đề cập đến trong một hàm. Thẻ @this phải được theo sau bởi một biểu thức loại.

Để ngăn trình biên dịch đưa ra cảnh báo, bạn phải sử dụng chú thích @this bất cứ khi nào this xuất hiện trong một hàm không phải là phương thức nguyên mẫu cũng không phải là hàm được đánh dấu là @constructor.

Ví dụ:

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

Dùng để ghi lại các ngoại lệ do một hàm gửi. Trình kiểm tra loại hiện không sử dụng thông tin này. Nó chỉ được dùng để tìm hiểu xem một hàm được khai báo trong tệp externs có tác dụng phụ hay không.

Ví dụ:

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

Xác định loại biến, thuộc tính hoặc biểu thức. Thẻ @type phải đi kèm với một biểu thức loại.

Khi khai báo một biến hoặc tham số hàm, bạn có thể viết chú thích loại nội tuyến mà không cần {} và @type, như trong ví dụ thứ hai. Bạn chỉ có thể thực hiện lối tắt này khi khai báo một biến hoặc tham số hàm. Nếu muốn điều chỉnh loại sau này, bạn sẽ cần một truyền kiểu.

Ví dụ:

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

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

Khai báo một biệt hiệu cho một loại phức tạp hơn. Hiện tại, bạn chỉ có thể xác định typedef ở cấp cao nhất, chứ không thể xác định bên trong các hàm. Chúng tôi đã khắc phục hạn chế này trong suy luận kiểu mới.

Ví dụ:

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

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

Cho biết rằng một lớp không phải là kiểu @struct cũng không phải là kiểu @dict. Đây là giá trị mặc định nên bạn thường không cần viết một cách rõ ràng, trừ phi bạn đang sử dụng từ khoá class. Cả hai từ khoá này đều tạo ra các lớp @struct theo mặc định.

Ví dụ:

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