Writing Documentation for a TypeScript Project: From A to Z

Introduction: Why Documentation is Needed in TypeScript Projects

High-quality documentation is not just a nice bonus, but a critically important element of any professional TypeScript project. It serves as a bridge between developers, facilitates the onboarding of new team members, and helps avoid errors when using the API. TypeScript, with its powerful type system, provides unique opportunities for generating accurate and self-documenting documentation. In this article, we will break down the complete process: from writing comments in code to publishing the finished documentation.

Basics: JSDoc and Annotations for TypeScript

TypeScript supports JSDoc syntax, which allows you to add structured comments directly into the code. This is the foundation for creating documentation that is understandable to both humans and tools.

Basic JSDoc Tags

Let's start with a simple example of a function that adds two numbers:

/**\n * Adds two numbers.\n * @param a - The first addend.\n * @param b - The second addend.\n * @returns The sum of two numbers.\n */\nfunction add(a: number, b: number): number {\n    return a + b;\n}

Key tags:

\n
• @param — describes a function argument. It is recommended to specify the type and purpose.
\n
• @returns — describes the return value.
\n
• @throws — indicates which exceptions the function can throw.
\n
• @example — shows a usage example.
\n

Documenting Complex Types

For interfaces and types, use @property or describe fields inside the block:

interface UserConfig {\n    /** User name */\n    name: string;\n    /** User age (optional) */\n    age?: number;\n    /** Role in the system */\n    role: 'admin' | 'user';\n}\n\n/**\n * Creates a user configuration.\n * @param config - Object with user settings.\n * @returns Configuration object.\n */\nfunction createUser(config: UserConfig): UserConfig {\n    return config;\n}

Use @template for generics:

/**\n * Wrapper for storing a value.\n * @template T - Type of the stored value.\n */\nclass Box<T> {\n    /** Stored value */\n    value: T;\n    constructor(value: T) {\n        this.value = value;\n    }\n}

Tools for Documentation Generation: TypeDoc

TypeDoc is the primary tool for automatically generating documentation from JSDoc annotations in TypeScript. It creates a static HTML site with convenient navigation.

Installation and Setup

Install TypeDoc as a dev dependency:

npm install --save-dev typedoc

Create a configuration file typedoc.json in the project root:

{\n  "entryPoints": ["src/index.ts"],\n  "out": "docs",\n  "theme": "default",\n  "excludePrivate": true,\n  "excludeProtected": false,\n  "includeVersion": true,\n  "categorizeByGroup": true\n}

Configuration parameters:

\n
• entryPoints — the entry point to your project (usually the main export file).
\n
• out — the folder where the documentation will be generated.
\n
• excludePrivate — hide private class members.
\n
• includeVersion — add the project version to the documentation.
\n

Running Generation

Add a script to package.json:

{\n  "scripts": {\n    "docs:generate": "typedoc"\n  }\n}

Execute the command:

npm run docs:generate

After this, a static site will appear in the docs folder. Open docs/index.html in your browser.

Best Practices for Writing Documentation

To make the documentation useful, follow a few rules.

1. Write Comments