@aigne/typedoc-plugin-example-utils-ts

A utility library for processing TypeDoc example code. This plugin allows you to remove specific function calls from code examples in the @example tags of TypeDoc documentation.

Installation

Using npm:

npm install @aigne/typedoc-plugin-example-utils-ts --save-dev

Using yarn:

yarn add @aigne/typedoc-plugin-example-utils-ts --dev

Using pnpm:

pnpm add @aigne/typedoc-plugin-example-utils-ts -D

Features

This plugin helps you remove specific function calls from code examples in TypeDoc documentation. This is particularly useful in the following scenarios:

• When your example code contains helper function calls that are only for demonstration purposes
• When you want to display more concise code examples in your documentation
• When you need to remove specific debugging or logging functions from examples

Configuration

Add the following options to your TypeDoc configuration file:

{
  "plugin": ["@aigne/typedoc-plugin-example-utils-ts"],
  "removeExpressionsFromExamples": ["spyOn", "expect", "jest.fn"]
}

The removeExpressionsFromExamples option accepts an array of strings specifying the function names to be removed from the example code.

How It Works

The plugin processes all @example tags during TypeDoc's resolveReflection phase. It uses TypeScript's AST (Abstract Syntax Tree) analysis to identify and remove the specified function calls.

Example

Suppose you have the following code with an @example tag:

/**
 * Calculate the sum of two numbers
 *
 * @param a The first number
 * @param b The second number
 * @returns The sum of the two numbers
 *
 * @example
 * ```ts
 * const calculator = ...
 * spyOn(calculator, 'add');
 * const result = calculator.add(1, 2);
 * expect(result).toBe(3);
 * return result;
 * ```
 */
function add(a: number, b: number): number {
  return a + b;
}

If you configure "removeExpressionsFromExamples": ["spyOn", "expect"], the example code in the generated documentation will become:

const calculator = ...
const result = calculator.add(1, 2);
return result;

Development

Clone the repository and install dependencies:

git clone <repository-url>
cd typedoc-plugin-example-utils-ts
pnpm install

Build the project:

pnpm build

License

MIT © Yechao Li