@remarks

Tag type: block tag

TSDoc standardization: core

The main documentation for an API item is separated into a brief "summary" section, optionally followed by a more detailed "remarks" section. On a documentation web site, index pages (e.g. showing members of a class) will show only the brief summaries, whereas a detail pages (e.g. describing a single member) will show the summary followed by the remarks. The @remarks block tag ends the summary section, and begins the remarks section for a doc comment.

NOTE: This design differs from JSDoc's approach, which uses an optional @summary tag to provide a condensed restatement of the full documentation. We experimented with this, but found that a well-written article already contains a "summary" in its first sentence or two.

Usage example:

/**
 * Represents an employee.
 *
 * @public
 */
export class Employee {
  /**
   * The employee's first name.
   *
   * @remarks
   * The first name may contain Unicode characters.
   */
  public firstName: string;

  /**
   * The employee's last name.
   *
   * @remarks
   * The last name may contain Unicode characters.
   */
  public lastName: string;

  /**
   * The employee's full name.
   *
   * @remarks
   * Returns the first name followed by the last name.
   */
  public getFullName(): string {
    return `${this.firstName} ${this.lastName}`;
  }
}

The index page for the class might show the summaries in tables like this:

Properties
Property Modifiers Type Description
firstName string The employee's first name.
lastName string The employee's last name.
Methods
Method Modifiers Description
getFullName() The employee's full name.

Property	Modifiers	Type	Description
firstName		`string`	The employee's first name.
lastName		`string`	The employee's last name.

Method	Modifiers	Description
getFullName()		The employee's full name.

Whereas the detail page for getFullName() would show the summary followed by the remarks:

Employee.getFullName() method
The employee's full name.
Signature:
getFullName(): string;
Returns: `string`
Remarks
Returns the first name followed by the last name.

See also​

See also