Writing Comments
Comment syntax
A JSDoc comment is a block comment that starts with /**:
/**
* The leading asterisk on each line is optional but conventional.
* JSDoc strips it automatically.
*/
Comments beginning with /* (one star) or /*** (three or more stars) are not parsed by JSDoc. Use them freely to write private notes.
Structure of a comment block
A comment block has two parts: the description and the tags.
/**
* [Description goes here — everything before the first @ tag]
*
* @tag1 ...
* @tag2 ...
*/
The description is plain text (or Markdown, if the Markdown plugin is enabled). It can span multiple lines and paragraphs.
Tags
Tags start with @ and follow the description. Tags may include:
| Part | Syntax | Required |
|---|---|---|
| Tag name | @param | Yes |
| Type | {string} | Optional |
| Name | myParam | Depends on tag |
| Description | - The description | Optional |
/**
* @param {string} name - The user's display name.
* @returns {string} A personalised greeting.
*/
function greet(name) {
return `Hello, ${name}!`;
}
Type expressions
Types appear inside {curly braces}. Any JavaScript type is valid:
| Expression | Meaning |
|---|---|
{string} | A string |
{number} | A number |
{boolean} | A boolean |
{Object} | Any object |
{string[]} | An array of strings |
{Array.<string>} | Same as above |
{string|number} | A string or a number |
{?string} | A nullable string |
{!string} | A non-nullable string |
{*} | Any type |
Block tags vs inline tags
Block tags stand alone on their own line and describe the symbol as a whole — @param, @returns, @type, etc.
Inline tags appear inside description text or the value of another tag, wrapped in {curly braces} — {@link}, {@tutorial}.
/**
* See the {@link Book} class for usage.
* @param {Book} book - The {@link Book} to process.
*/
Multiline tags
Long tag descriptions can wrap onto the next line. Indent continuation lines for readability:
/**
* @param {Object} options - Configuration options.
* @param {string} options.host - The server hostname.
* @param {number} [options.port=3000] - The server port.
* Defaults to 3000 when not provided.
*/
Optional parameters and defaults
Wrap a parameter name in [square brackets] to mark it as optional. Specify a default with =:
/**
* @param {string} [separator=','] - The list separator.
*/
Next steps
Browse the complete Tags reference to see every tag JSDoc understands.
Official reference: Official JSDoc documentation