Writing Documentation for a TypeScript Project: From A to Z

Introduction: Why Documentation is an Investment, Not a Waste of Time

Every developer has encountered this situation: returning to your own code after a month, you struggle to remember why a particular parameter is needed. Not to mention new team members trying to understand your project. High-quality documentation for a TypeScript project is not just a nice addition, but a critically important element that accelerates onboarding, reduces the number of bugs, and makes the code maintainable.

TypeScript, being a superset of JavaScript, provides a powerful type system. However, types alone do not always answer the question "why." Documentation fills this gap. In this article, we will cover the complete cycle: from choosing a comment style to generating a static documentation site.

1. Basics: JSDoc, TSDoc, and TypeScript

For documenting TypeScript code, two main standards have historically emerged: JSDoc and TSDoc. JSDoc is the good old format that came from the JavaScript world. TSDoc is a more modern standard, optimized specifically for TypeScript. Both approaches use comments in the format /** ... */.

Let's look at a basic example using JSDoc:

/** * Calculates the sum of two numbers. * @param a - The first addend * @param b - The second addend * @returns The sum of a and b */function add(a: number, b: number): number {    return a + b;}

Here is how it looks in TSDoc style using the @param and @returns tags:

/** * Calculates the sum of two numbers. * @param a - The first addend * @param b - The second addend * @returns The sum of a and b */function add(a: number, b: number): number {    return a + b;}

The difference is minimal, but TSDoc adds support for TypeScript-specific constructs such as generics and conditional types.

1.1 Documenting Interfaces and Types

Special attention should be paid to interfaces and types. They are the "skeleton" of a TypeScript project. Here is an example of a well-documented interface:

/** * Represents a system user. */interface User {    /** Unique user identifier */    id: string;    /** Full user name */    name: string;    /** Email address (must be unique) */    email: string;    /** Date of last login (optional) */    lastLogin?: Date;    /** User role in the system */    role: 'admin' | 'user' | 'moderator';}

Note: each interface parameter has its own /** ... */ comment. This allows the IDE (e.g., VS Code) to show hints when using this interface.

2. Advanced Techniques: Generics and Conditional Types

TypeScript is famous for its type system, and documentation should reflect its complexity. This is especially true for generics (generic types) and conditional types.

Let's look at an example of a generic with documentation:

/** * Creates an array from a single element of type T. * @template T - The type of the element to be placed in the array * @param item - The element to wrap * @returns An array containing the passed element */function wrapInArray<T>(item: T): T[] {    return [item];}

The @template tag explicitly indicates what T is. This is especially useful when there are multiple generics or they have a complex relationship.

For conditional types, documentation becomes even more important. Example:

/** * Extracts the value type from a Promise if a Promise is passed. * Otherwise, returns the original type. * @template T - The type that may or may not be a Promise * @example * // For Promise<number> returns number * type Result = UnwrapPromise<Promise<number>>; // number