Include code examples in your typedoc documentations.

Installation

$ npm install --save-dev typedoc-plugin-include-example

Usage

Write your example in a file.

import { greet } from "./greet.js"
greet();

Add the @includeExample tag with the example path.

/**
 * @includeExample src/greet.example.js
 */
export function greet() {
    console.log("Hello there.")
}

Then generate your documentation using typedoc.

$ npx typedoc --plugin typedoc-plugin-include-example

Why including examples ?

Demonstrating how to use with examples has always been an essential part of making documentations accessible for newcomers. This plugin provides a conventionnal way of defining examples within your whole documentation.

Files as example never get out of date. If you're using type checking or other tools for code validation, example will need to be updated to follow the project evolutions.

Best practice

I recommend to include a whole file for each example, not specific lines, because line numbers can quickly get out of date. In the future I'll make the file path optionnal, making the convention ./<sourceFile>.example.<extention> the default for example file paths.

Features

• Selecting specific lines.
• Selecting line ranges.
• Using multiple selections.

See the Documentation for full usage.

Links

• Typedoc's website.
• Package on Npm.
• Demonsration of what examples looks like.
• Documentation detailling specific features.
• Coverage testing report to visualise unit testing efficiency.