Đá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 bớt 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 tạo một cảnh báo nếu một phương thức được đánh dấu bằng @abstract có cách triển khai không trống.

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

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

Phần khai báo loại là không bắt buộc.

Trình biên dịch tạo một cảnh báo nếu một biến được đánh dấu bằng @const được gán một 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ú thích @constructor cho bất kỳ hàm nào đượ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 để sử dụng sẽ tạo ra cảnh báo của trình biên dịch cho biết rằng hàm đó không còn được sử dụng 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 khởi tạo (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 đơn để 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 giá trị cố định của đố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 enum. Enum là một đối tượng có các thuộc tính cấu thành một tập hợp các hằng số có liên quan. Theo sau thẻ @enum phải là 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. Chẳng hạn nếu một enum có loại number, mỗi thuộc tính được liệt kê phải là một số. Nếu loại enum bị bỏ qua, thì giả định number.

Ví dụ:

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

Đã cung cấp mã này

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

khi trình biên dịch được chạy bằng cờ --generate_exports, trình biên dịch này sẽ tạo mã:

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

Thao tác này sẽ xuất các ký hiệu sang mã chưa biên dịch. Bạn có thể viết /** @export {SomeType} */ viết tắt của

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

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

1. bao gồm closure/base.js, hoặc
2. khai báo cả goog.exportSymbol và goog.exportProperty bằng cùng một chữ ký phương thức trong cơ sở mã của riêng 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. 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 chỉ đơn giản 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 lớp khác trong quá trình kiểm tra loại.

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

Ví dụ:

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

Cho biết rằng lớp này không được phép mở rộng. Đối với các phương thức, hãy 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 sẽ triển khai giao diện.

Trình biên dịch tạo một cảnh báo nếu bạn gắn thẻ một hàm dựng bằng @implements, sau đó không triển khai được 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 nội dung khai báo về tài sản bên ngoài. Thuộc tính có một loại đã khai báo, nhưng bạn có thể chỉ định bất kỳ loại nào cho loại đó 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 một giá trị của loại đã khai báo. Ví dụ: element.innerHTML có thể được gán 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 một lớp con đã cố ý ẩn một phương thức hoặc thuộc tính của lớp cao cấp và có chính xác cùng một tài liệu. 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 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. Xem @implements.

Trình biên dịch xác minh rằng giao diện không được tạo bản sao. Nếu bạn sử dụng từ khóa new cùng với một hàm giao diện, thì trình biên dịch sẽ tạo ra một 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 cố định phải được xem là thuộc tính của một số đối tượng khác. Chú thích này chỉ được xuất hiện trên giá trị cố định của đối tượng.

Hãy 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. Đó là tên đối tượng. Công cụ này đặt tên cho đối tượng mà các thuộc tính cho mượn. Ví dụ: @type {Foo} có nghĩa là "một bản sao 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 liên quan 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) không bị thay đổi. 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:
 */

Mô tả một thuộc tính mà trình biên dịch không nên thu gọn thành một biến. Mục đích sử dụng chính của @nocollapse là cho phép xuất các thuộc tính có thể thay đổi. 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 bị thu gọn. Nếu bạn chú thích một thuộc tính là một đối tượng có @nocollapse, thì tất cả các thuộc tính đó cũng sẽ 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ú thích 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 sử dụng. Chỉ được 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 một lớp con sẽ cố ý ẩn một phương thức hoặc thuộc tính của lớp cao cấp. Nếu không có chú thích nào khác được đưa vào, phương thức hoặc thuộc tính đó sẽ tự động kế thừa các chú thích từ lớp cao cấp.

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 tài sản là gói riêng tư. Chỉ mã trong cùng thư mục mới có thể truy cập vào tên được đánh dấu là @package. Cụ thể, mã trong thư mục mẹ và thư mục con không thể truy cập vào tên có nhãn @package.

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

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 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. Các thẻ @param phải theo cùng thứ tự với thông 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ú thích các loại tham số cùng dòng (xem ví dụ về hàm foo).

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 toàn cục được đánh dấu là @private. Hàm khởi tạo được đánh dấu @private chỉ có thể được tạo bản sao bằng mã trong cùng một tệp và bằng các thành phần tĩnh và thực thể của các hàm khởi tạo đó.

Bạn cũng có thể truy cập vào các thuộc tính tĩnh công khai của các hàm khởi tạo có nhãn @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 viên hoặc tài sản được bảo vệ.

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

• tất cả mã trong cùng một tệp
• phương thức tĩnh và phương thức thực thể của bất kỳ lớp con nào 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à mọi lớp bao gồm các phương thức và thuộc tính được xác định trên prototoype của giao diện cấu trúc sẽ triển khai giao diện cấu trúc, cho dù giao diện đó có sử dụng thẻ @implements hay không. Các loại bản ghi và giá trị cố định đối tượng cũng ngầm triển khai giao diện cấu trúc nếu các giao diện này 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 loại dữ liệu trả về cho các phương thức định nghĩa hàm và phương thức. 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 loại dữ liệu trả về nội tuyến (xem ví dụ về hàm foo).

Nếu một hàm không ở ngoài bộ nhớ ngoài 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 khởi tạo (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 phải ký hiệu dấu ngoặc. Ngoài ra, bạn không thể thêm thuộc tính vào thực thể Foo sau khi tạo. Bạn cũng có thể sử dụng chú thích trực tiếp trên các giá trị cố định của đố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 mục 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 tham chiếu trong một hàm. Thẻ @this phải được theo sau bởi một biểu thức loại.

Để ngăn cảnh báo của trình biên dịch, 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 hoặc một 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 nhận các trường hợp 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. Lệnh này chỉ được dùng để xác định 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. Theo sau thẻ @type là 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 kiểu cùng dòng bỏ qua {} và @type như trong ví dụ thứ hai. Bạn chỉ có thể thực hiện phím 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 cần có 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, typedef chỉ có thể được xác định ở cấp cao nhất, không phải trong hàm. Chúng tôi đã khắc phục hạn chế này trong suy luận kiểu dữ liệ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 lớp không phải là loại @struct hoặc loại @dict. Đây là giá trị mặc định nên thường không cần thiết phải viết một cách rõ ràng, trừ phi bạn đang dùng goog.defineClass hoặc từ khoá class, cả hai đều tạo 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