RFC: Syntax for @example tag

[octogonz]

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

[dend]

In the case of DocFX, we definitely want to move away from inlined samples and into includes (see: file inclusion). As such, I like the proposal of having the tag be Markdown-ready.

[tenry92]

I always thought @example is always followed by a sample code, or at least a link to an example file.

If there will be some kind of {@include} (see #22), I would suggest using that in conjunction with markdown, as in the first comment:

/**
 * Adds two numbers together.
 * @example
 * Here's a simple example:
 * {@include example1.ts}
 * @example
 * Here's an example with negative numbers:
 * {@include example2.ts}
 */
export function add(x: number, y: number): number {
}

This way, it's easy to include several code snippets within the same example and reuse example codes at several places.

[aciccarello]

@pgonzal I'm not sure I understand your question but the code you have looks good to me. My main question is where should the example tag block end? Would it be on an empty line or the next block annotation?

[DovydasNavickas]

@aciccarello I guess your question will be answered here: #12

[kiliancs]

@example could be spec'ed in such a way that it can be used for tests.

/* @example
/* > plusOne(3)
/* 4

One could create a tool that executes plusOne(3) and fails if the result is not 4.

I haven't given much thought to the different scenarios and why this might or might not make sense in the context of JS/TS. Maybe we need a new tag.

/* @example addOne(3)
/* @expect 4

Sorry for the brainstorming.

[aciccarello]

@kiliancs That seems to me like something that should stay in the example code and not be handled by the documentation tool. Interesting idea though.

/**
 * @example
 * Adding one adds one
 * ```typescript
 * import plusOne from 'plus-one';
 * import expect from 'test-lib';
 *
 * const actual = plusOne(3);
 * expect(actual).toEqual(4);
 * ```
 */
export function plusOne(input: number) {
  return input + 1;
}

[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 {};
 * ```

[sharwell]

Recently I've been starting to question the need for a dedicated @example tag. It seems like ## Example (a Markdown header) may be able to do the job just as well without defining a new tag.

[octogonz]

I suppose depends on your documentation template. Right now API Extractor renders @example blocks basically as headers like you suggest, with a bit of extra logic to autonumber the examples if there are more than one of them. But you could imagine a more elaborate system that indexes the examples, or shows special icons next to example sections, etc.

@dend Does DocFX treat example sections differently from other sections?

[vogloblinsky]

Right now API Extractor renders @example blocks

@pgonzal did this work or release in last npm version deployed ?

I just made a test with your playground this morning with my-use case and cannot see informations in the AST generated.