RFC: Syntax for @example tag

RFC: Core set of tags for TSDoc brought up the question of the @example tag that could be used to identify examples. I’m forking it into a separate issue since @c69 pointed out that the design is unclear.

Can anyone find samples of its usage in existing documentation systems?

Since TSDoc will support Markdown, how would it interact with that? Maybe something like this?

/**
 * Adds two numbers together.
 * @example
 * Here's a simple example:
 * ```
 * // Prints "2":
 * console.log(add(1,1));
 * ```
 * @example
 * Here's an example with negative numbers:
 * ```
 * // Prints "0":
 * console.log(add(1,-1));
 * ```
 */
export function add(x: number, y: number): number {
}

How would an API reference web site leverage these directives?

@aciccarello

[octogonz]

That’s a good suggestion. Currently API Documenter simply generates names like Example 1, Example 2, etc. Not as informative as it could be.

Maybe in @example Name - ... format, or take the text on the same line as the tag to be the name.

There’s already some precedent, where the @throws tag has a convention that the exception name can be specified using text on the same line as the tag.

   /**
    * Retrieves metadata about a book from the catalog.
    *    
    * @param isbnCode - the ISBN number for the book
    * @returns the retrieved book object
    *
    * @throws {@link IsbnSyntaxError}
    * This exception is thrown if the input is not a valid ISBN number.
    *
    * @throws {@link book-lib#BookNotFoundError}
    * Thrown if the ISBN number is valid, but no such book exists in the catalog.
    *
    * @public
    */
    function fetchBookByIsbn(isbnCode: string): Book;

So maybe a similar convention could be used for @example as in your sample. (BTW markdown headers should probably start with #, to avoid making assumptions about the documenter’s heading structure.)

So it could be like this:

/**
 * Parses a JSON file.
 *
 * @param path - Full path to the file.
 * @returns An object containing the JSON data.
 *
 * @example Parsing a basic JSON file
 *
 * # Contents of `file.json`
 * ```json
 * {
 *   "exampleItem": "text"
 * }
 * ```
 *
 * # Usage
 * ```ts
 * const result = parseFile("file.json");
 * ```
 *
 * # Result
 * ```ts
 * {
 *   exampleItem: 'text',
 * }
 * ```
 */

…and might get rendered like this:

---

Example: Parsing a basic JSON file

Contents of file.json

{
  "exampleItem": "text"
}

Usage

const result = parseFile("file.json");

Result

{
  exampleItem: 'text',
}

[vogloblinsky]

@pgonzal I can have for Angular documentation tool https://github.com/compodoc/compodoc this kind of @example usage which use TypeScript decorator.

 * @example
 * Usage example
 * ```typescript
 * @Component({selector: 'something'}) export class AppComponent {};
 * ```