Improve this page

@remarks

Tag type: block tag

TSDoc standardization: extended

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.

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