Properties
Write a doc comment for all (i.e. @api) properties. Similarly to when documenting methods, the @description tag is not required. Use only the tags listed below:
| Tag | Description |
|---|---|
@type {type} | Documents the property type |
@typedef {typedef} | Documents the type of a custom object |
@property {type} | Documents the type of an object's property |
@deprecated | Documents that the property should no longer be used |
Below is an example of a JSDoc property doc comment:
/**
* If true, shows the tab detail to the user; if false, shows nothing
* @type {boolean}
*/
@api isDetailVisible;
@type
Include the property type after the @type tag. Enclose it in curly braces; e.g. @type {string}. Use the @type tag only when the type is known.
Only use types included in the Closure Type System or those defined by a @typedef tag.
@typedef
@typedef tags define custom types, such as complex type with many properties (i.e. objects) or a type that can be one of multiple other types. After defining a custom type, you can reference its definition elsewhere in documentation.
When documenting an object, do so in its own doc comment preceding its use in code. Follow the @typedef tag with {Object}, with each succeeding line documenting a property of the type using the @property tag. Below is an example of a @typedef tag defining a complex type, later used to document a parameter for a function:
/**
* The complete Triforce, or one or more components of the Triforce.
* @typedef {Object} Triforce
* @property {boolean} hasCourage - True if the Courage component is present.
* @property {boolean} hasPower - True if the Power component is present.
* @property {boolean} hasWisdom - True if the Wisdom component is present.
*/
/**
* A function for granting wishes, powered by the Triforce.
* @param {...Triforce} triforce - One to three {@link Triforce} objects
* containing all three components of the Triforce.
*/
function WishGranter(triforce) {}
Alternatively, use the @typedef tag to document where a type is one of multiple existing types. Below is an example of the @typedef tag documenting a type that could either be a number or a string:
/**
* A number, or a string containing a number.
* @typedef {(number|string)} NumberLike
*/
/**
* Set the magic number.
* @param {NumberLike} x - The magic number.
*/
function setMagicNumber(x) {
}
For more information on the @typedef tag, consult the JSDoc documentation.
@deprecated
Accompany the @deprecated tag with the name of the release that deprecated the property (e.g. June 2024). Link to whichever property should be used instead with the format {@link namepath}. Optionally, explain why the property was deprecated.