Last updated
TypeDoc Generator Examples
The TypeDoc Generator creates TypeDoc configuration files and JSDoc comment templates for TypeScript projects. Below are practical examples for typedoc.json configuration and documentation comment patterns.
Basic typedoc.json Configuration
{
"entryPoints": ["src/index.ts"],
"out": "docs",
"theme": "default",
"name": "My Library",
"includeVersion": true,
"readme": "README.md",
"excludePrivate": true,
"excludeProtected": false,
"excludeExternals": true
}
Multiple Entry Points (Monorepo)
{
"entryPoints": [
"packages/core/src/index.ts",
"packages/utils/src/index.ts",
"packages/types/src/index.ts"
],
"entryPointStrategy": "packages",
"out": "docs",
"name": "My Monorepo",
"includeVersion": true
}
Function Documentation Comment
/**
* Calculates the total price including tax and optional discount.
*
* @param subtotal - The pre-tax price in cents
* @param taxRate - The tax rate as a decimal (e.g., 0.08 for 8%)
* @param discount - Optional discount amount in cents (default: 0)
* @returns The total price in cents including tax minus discount
* @throws {RangeError} If subtotal or taxRate is negative
*
* @example
* ```typescript
* const total = calculateTotal(1000, 0.08);
* // Returns 1080 (1000 + 80 tax)
*
* const discounted = calculateTotal(1000, 0.08, 100);
* // Returns 980 (1000 + 80 tax - 100 discount)
* ```
*/
function calculateTotal(subtotal: number, taxRate: number, discount = 0): number {
if (subtotal < 0 || taxRate < 0) {
throw new RangeError('subtotal and taxRate must be non-negative');
}
return Math.round(subtotal * (1 + taxRate) - discount);
}
Class Documentation Comment
/**
* HTTP client with automatic retry and timeout handling.
*
* @example
* ```typescript
* const client = new HttpClient({
* baseUrl: 'https://api.example.com',
* timeout: 5000,
* retries: 3
* });
*
* const users = await client.get<User[]>('/users');
* ```
*/
class HttpClient {
/**
* Creates a new HttpClient instance.
*
* @param options - Configuration options for the client
*/
constructor(private readonly options: HttpClientOptions) {}
/**
* Sends a GET request to the specified path.
*
* @typeParam T - The expected response body type
* @param path - The URL path relative to baseUrl
* @param params - Optional query parameters
* @returns A promise resolving to the response body
* @throws {HttpError} If the request fails or returns a non-2xx status
*/
async get<T>(path: string, params?: Record<string, string>): Promise<T> {
// implementation
}
/**
* Sends a POST request with a JSON body.
*
* @typeParam TBody - The request body type
* @typeParam TResponse - The expected response body type
* @param path - The URL path relative to baseUrl
* @param body - The request body (will be JSON-serialized)
* @returns A promise resolving to the response body
*/
async post<TBody, TResponse>(path: string, body: TBody): Promise<TResponse> {
// implementation
}
}
Interface Documentation
/**
* Configuration options for the HttpClient.
*/
interface HttpClientOptions {
/** The base URL for all requests (e.g., 'https://api.example.com') */
baseUrl: string;
/** Request timeout in milliseconds (default: 10000) */
timeout?: number;
/** Number of retry attempts for failed requests (default: 0) */
retries?: number;
/** Default headers to include with every request */
headers?: Record<string, string>;
}
/**
* Represents a paginated API response.
*
* @typeParam T - The type of items in the data array
*/
interface PaginatedResponse<T> {
/** The items in the current page */
data: T[];
/** Total number of items across all pages */
total: number;
/** Current page number (1-indexed) */
page: number;
/** Number of items per page */
pageSize: number;
/** Whether there are more pages after this one */
hasNextPage: boolean;
}
Enum Documentation
/**
* HTTP status code categories.
*/
enum HttpStatusCategory {
/** 1xx Informational responses */
Informational = 100,
/** 2xx Success responses */
Success = 200,
/** 3xx Redirection responses */
Redirection = 300,
/** 4xx Client error responses */
ClientError = 400,
/** 5xx Server error responses */
ServerError = 500,
}
Generic Function Documentation
/**
* Creates a memoized version of a function that caches results.
*
* @typeParam TArgs - The argument types of the function
* @typeParam TReturn - The return type of the function
* @param fn - The function to memoize
* @param keyFn - Optional function to generate cache keys (default: JSON.stringify)
* @returns A memoized version of the input function
*
* @example
* ```typescript
* const expensiveCalc = memoize((n: number) => fibonacci(n));
* expensiveCalc(40); // computed
* expensiveCalc(40); // returned from cache
* ```
*/
function memoize<TArgs extends unknown[], TReturn>(
fn: (...args: TArgs) => TReturn,
keyFn?: (...args: TArgs) => string
): (...args: TArgs) => TReturn {
// implementation
}
Full typedoc.json with All Options
{
"entryPoints": ["src/index.ts"],
"out": "docs",
"theme": "default",
"name": "My TypeScript Library",
"includeVersion": true,
"readme": "README.md",
"excludePrivate": true,
"excludeProtected": false,
"excludeExternals": true,
"excludeNotDocumented": false,
"categorizeByGroup": true,
"defaultCategory": "Other",
"navigationLinks": {
"GitHub": "https://github.com/myorg/mylib",
"npm": "https://www.npmjs.com/package/mylib"
},
"plugin": ["typedoc-plugin-markdown"],
"tsconfig": "tsconfig.json",
"compilerOptions": {
"strictNullChecks": true
}
}
package.json Scripts
{
"scripts": {
"docs": "typedoc",
"docs:watch": "typedoc --watch",
"docs:serve": "typedoc && npx serve docs"
},
"devDependencies": {
"typedoc": "^0.25.0",
"typedoc-plugin-markdown": "^4.0.0"
}
}
GitHub Actions — Auto-Deploy Docs
name: Deploy Documentation
on:
push:
branches: [main]
jobs:
docs:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- uses: actions/setup-node@v4
with:
node-version: '20'
- run: npm ci
- run: npm run docs
- uses: peaceiris/actions-gh-pages@v3
with:
github_token: ${{ secrets.GITHUB_TOKEN }}
publish_dir: ./docs
JSDoc Tag Reference for TypeDoc
- @param name - description: documents a function parameter
- @returns description: documents the return value
- @throws {ErrorType} description: documents thrown exceptions
- @typeParam T - description: documents a generic type parameter
- @example: provides a usage example (supports code blocks)
- @deprecated message: marks a declaration as deprecated
- @since version: indicates when the API was added
- @see reference: links to related documentation
- @internal: excludes from public documentation
- @category name: groups declarations in the documentation
Use the TypeDoc Generator to create your typedoc.json configuration and generate JSDoc comment templates for your TypeScript declarations.