Methods
Write a doc comment for all public (i.e. @api) methods and export modules. Omit the @description tag as it is unnecessary; in JSDoc doc comments, any text before the first tag is the description.
When writing JSDoc descriptions, follow the same principles behind ApexDocs descriptions.
Use only the below tags and in the order listed:
| Tag | Description |
|---|---|
@param {type} paramName | Description of a single parameter |
@returns {type} | Description of the return value of the method |
@fires | References a specific event this method may fire |
@listens | References a specific event that the method listens for |
@throws ExceptionName | Description of an exception thrown by the method |
@see namepath/url | References a relevant method or external resource |
@deprecated | Documents that the method should no longer be used |
Below is an example of a JSDoc method doc comment:
/**
* Validates all characters in the user input.
* @param {string} input - The user input
* @returns {boolean} True if valid - False if not
* @fires module:foo/bar.event:InputValidated
* @listens module:foo/bar.event:InputReceived
* @throws IllegalCharException if the user input could not be parsed
*/
@api validate(String input) {
// TODO: perform validation
}
It may be tempting to include @link tags in the description, but as they can degrade readability use them with only the @see and @deprecated tags.
@param
Include the @param tag for each parameter. Enclose the type in curly braces ({}) and follow with the name, a hyphen (-) and finally the description.
Only use types included in the Closure Type System or those defined by a @typedef tag.
@returns
Attach to the @returns tag the type enclosed in curly braces, followed by a description of the returned variable. Where the properties of the returned variable depends on a condition, include a @returns tag for each condition and explain it.
Where the return type is void, omit the @returns tag.
@fires
Pair each @fires tag with the namepath of the fired event.
The JSDoc documentation details the use of namepaths.
@listens
Pair each @listens tag with the namepath of the event listened for.
@throws
Pair each @throws tag with the name of the exception thrown. Follow this by explaining the condition that causes the exception to be thrown.
@see
Accompany @see tags with either the related method’s namepath, or a link to external documentation in the format {@link <url>}. Optionally, explain why the method or documentation has been linked to.
@deprecated
Similarly to ApexDocs comments, the @deprecated tag precedes the release that deprecated the method (e.g. June 2024). Link to whichever method should be used instead with the format {@link namepath}. Optionally, explain why the method was deprecated.