microsoft / tsdoc

A doc comment standard for TypeScript
https://tsdoc.org/
MIT License
4.68k stars 131 forks source link

[Question] Is there a way to generate the "@example" tag contents from an external source file? #344

Open satelllte opened 1 year ago

satelllte commented 1 year ago

For example,

Here's the source file:

/* source/add.ts */

/**
 * Adds two numbers.
 *
 * @param x - First number.
 * @param y - Second number
 * @returns The sum of x and y.
 */
const add = (x: number, y: number): number => x + y

Here's the example source file:

/* examples/add.ts */

import { add } from '@source/add'

add(2, 3) // 5

Is there a way to reference the example source file in TSDoc?

Ideally via something like this:

/* pseudo-code */

/**
 * @example {@ref(./examples/add.ts)}
 */

The key benefit to have such ability is to have a single source of example without any duplications to be able to present it in a multiple ways simultaneously, like running it and listing its source at the same time.