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

Start with the linked RFC issue and the examples in this issue, then compare how existing documentation systems represent example tags. Resolve how @example interacts with Markdown and how API reference sites should use it. Done means the syntax and its rendering semantics are agreed and documented.