majiayu000 JSDoc TypeScript Documentation
Create comprehensive inline documentation for TypeScript codebases.
Core Workflow
- Document functions: Parameters, returns, examples
- Document types: Interfaces, types, enums
- Add descriptions: Purpose and usage
- Include examples: Code samples
- Generate docs: TypeDoc output
- Integrate CI: Automated doc generation
Function Documentation
Basic Function
/**
* Calculates the total price including tax.
*
* @param price - The base price before tax
* @param taxRate - The tax rate as a decimal (e.g., 0.08 for 8%)
* @returns The total price including tax
*
* @example
* ```typescript
* const total = calculateTotal(100, 0.08);
* console.log(total); // 108
* ```
*/
export function calculateTotal(price: number, taxRate: number): number {
return price * (1 + taxRate);
}
Async Function
/**
* Fetches user data from the API.
*
* @param userId - The unique identifier of the user
* @param options - Optional configuration for the request
* @returns A promise that resolves to the user data
*
* @throws {NotFoundError} When the user doesn't exist
* @throws {NetworkError} When the request fails
*
* @example
* ```typescript
* try {
* const user = await fetchUser('user-123');
* console.log(user.name);
* } catch (error) {
* if (error instanceof NotFoundError) {
* console.log('User not found');
* }
* }
* ```
*/
export async function fetchUser(
userId: string,
options?: FetchOptions
): Promise<User> {
const response = await fetch(`/api/users/${userId}`, options);
if (response.status === 404) {
throw new NotFoundError(`User ${userId} not found`);
}
if (!response.ok) {
throw new NetworkError('Failed to fetch user');
}
return response.json();
}
Generic Function
/**
* Filters an array based on a predicate function.
*
* @typeParam T - The type of elements in the array
* @param array - The array to filter
* @param predicate - A function that returns true for elements to keep
* @returns A new array containing only elements that pass the predicate
*
* @example
* ```typescript
* const numbers = [1, 2, 3, 4, 5];
* const evens = filterArray(numbers, n => n % 2 === 0);
* // evens: [2, 4]
* ```
*/
export function filterArray<T>(
array: T[],
predicate: (item: T, index: number) => boolean
): T[] {
return array.filter(predicate);
}
Overloaded Function
/**
* Formats a value for display.
*
* @param value - The value to format
* @returns The formatted string
*/
export function format(value: number): string;
/**
* Formats a value with a specific format string.
*
* @param value - The value to format
* @param formatStr - The format string (e.g., 'currency', 'percent')
* @returns The formatted string
*/
export function format(value: number, formatStr: string): string;
/**
* @internal
*/
export function format(value: number, formatStr?: string): string {
if (formatStr === 'currency') {
return `$${value.toFixed(2)}`;
}
if (formatStr === 'percent') {
return `${(value * 100).toFixed(1)}%`;
}
return value.toString();
}
Interface Documentation
/**
* Represents a user in the system.
*
* @example
* ```typescript
* const user: User = {
* id: 'user-123',
* email: 'john@example.com',
* name: 'John Doe',
* role: 'admin',
* createdAt: new Date(),
* };
* ```
*/
export interface User {
/**
* The unique identifier for the user.
* @example 'user-123'
*/
id: string;
/**
* The user's email address.
* @example 'john@example.com'
*/
email: string;
/**
* The user's display name.
* @example 'John Doe'
*/
name: string;
/**
* The user's role in the system.
* @default 'user'
*/
role: 'admin' | 'user' | 'guest';
/**
* When the user account was created.
*/
createdAt: Date;
/**
* When the user account was last updated.
* @optional
*/
updatedAt?: Date;
/**
* The user's profile settings.
* @see {@link UserProfile}
*/
profile?: UserProfile;
}
/**
* User profile configuration.
*/
export interface UserProfile {
/** URL to the user's avatar image */
avatarUrl?: string;
/** User's preferred language code (e.g., 'en', 'es') */
language: string;
/** User's timezone (e.g., 'America/New_York') */
timezone: string;
/** User notification preferences */
notifications: NotificationSettings;
}
Type Documentation
/**
* HTTP methods supported by the API.
*/
export type HttpMethod = 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE';
/**
* Configuration options for API requests.
*
* @typeParam TBody - The type of the request body
*/
export type RequestConfig<TBody = unknown> = {
/** HTTP method to use */
method: HttpMethod;
/** Request headers */
headers?: Record<string, string>;
/** Request body (for POST, PUT, PATCH) */
body?: TBody;
/** Request timeout in milliseconds */
timeout?: number;
/** Number of retry attempts on failure */
retries?: number;
};
/**
* Result type for operations that can fail.
*
* @typeParam T - The type of the success value
* @typeParam E - The type of the error value
*
* @example
* ```typescript
* function divide(a: number, b: number): Result<number, string> {
* if (b === 0) {
* return { success: false, error: 'Division by zero' };
* }
* return { success: true, data: a / b };
* }
* ```
*/
export type Result<T, E = Error> =
| { success: true; data: T }
| { success: false; error: E };
Class Documentation
/**
* A client for interacting with the API.
*
* @remarks
* This client handles authentication, retries, and error handling
* automatically. Use the {@link ApiClient.create} factory method
* to create an instance.
*
* @example
* ```typescript
* const client = ApiClient.create({
* baseUrl: 'https://api.example.com',
* apiKey: process.env.API_KEY,
* });
*
* const users = await client.get<User[]>('/users');
* ```
*/
export class ApiClient {
/**
* The base URL for all API requests.
* @readonly
*/
readonly baseUrl: string;
/**
* Creates a new ApiClient instance.
*
* @param config - The client configuration
* @returns A new ApiClient instance
*
* @example
* ```typescript
* const client = ApiClient.create({ baseUrl: 'https://api.example.com' });
* ```
*/
static create(config: ApiClientConfig): ApiClient {
return new ApiClient(config);
}
/**
* @internal
*/
private constructor(private config: ApiClientConfig) {
this.baseUrl = config.baseUrl;
}
/**
* Performs a GET request.
*
* @typeParam T - The expected response type
* @param endpoint - The API endpoint (relative to baseUrl)
* @param options - Optional request configuration
* @returns A promise that resolves to the response data
*
* @throws {ApiError} When the request fails
*
* @example
* ```typescript
* interface User { id: string; name: string; }
* const users = await client.get<User[]>('/users');
* ```
*/
async get<T>(endpoint: string, options?: RequestOptions): Promise<T> {
return this.request<T>('GET', endpoint, options);
}
/**
* Performs a POST request.
*
* @typeParam T - The expected response type
* @typeParam TBody - The request body type
* @param endpoint - The API endpoint
* @param body - The request body
* @param options - Optional request configuration
* @returns A promise that resolves to the response data
*/
async post<T, TBody = unknown>(
endpoint: string,
body: TBody,
options?: RequestOptions
): Promise<T> {
return this.request<T>('POST', endpoint, { ...options, body });
}
/**
* @internal
*/
private async request<T>(
method: HttpMethod,
endpoint: string,
options?: RequestOptions
): Promise<T> {
// Implementation
}
}
Enum Documentation
/**
* Status codes for order processing.
*
* @remarks
* Orders progress through these statuses in sequence,
* though they may skip directly to `Cancelled` from any state.
*/
export enum OrderStatus {
/** Order has been created but not yet processed */
Pending = 'pending',
/** Payment has been received and order is being prepared */
Processing = 'processing',
/** Order has been shipped to the customer */
Shipped = 'shipped',
/** Order has been delivered to the customer */
Delivered = 'delivered',
/** Order has been cancelled */
Cancelled = 'cancelled',
/** Order has been returned by the customer */
Returned = 'returned',
}
React Component Documentation
/**
* A customizable button component.
*
* @remarks
* This button supports multiple variants, sizes, and states.
* It is fully accessible and supports keyboard navigation.
*
* @example
* ```tsx
* // Basic usage
* <Button me</Button>
*
* // With variant and size
* <Button variant="secondary" size="lg">
* Large Secondary Button
* </Button>
*
* // Loading state
* <Button loading>Submitting...</Button>
* ```
*/
export interface ButtonProps
extends React.ButtonHTMLAttributes<HTMLButtonElement> {
/**
* The visual style variant.
* @default 'primary'
*/
variant?: 'primary' | 'secondary' | 'outline' | 'ghost';
/**
* The size of the button.
* @default 'md'
*/
size?: 'sm' | 'md' | 'lg';
/**
* Whether the button is in a loading state.
* When true, the button is disabled and shows a spinner.
* @default false
*/
loading?: boolean;
/**
* Icon to display before the button text.
*/
leftIcon?: React.ReactNode;
/**
* Icon to display after the button text.
*/
rightIcon?: React.ReactNode;
}
/**
* A customizable button component.
*
* @param props - The component props
* @returns The rendered button element
*
* @see {@link ButtonProps} for available props
*/
export const Button = React.forwardRef<HTMLButtonElement, ButtonProps>(
({ variant = 'primary', size = 'md', loading, children, ...props }, ref) => {
// Implementation
}
);
Button.displayName = 'Button';
TypeDoc Configuration
// typedoc.json
{
"entryPoints": ["./src/index.ts"],
"out": "./docs",
"name": "My Library",
"readme": "./README.md",
"plugin": [
"typedoc-plugin-markdown",
"typedoc-plugin-mdn-links"
],
"excludePrivate": true,
"excludeProtected": true,
"excludeInternal": true,
"includeVersion": true,
"categorizeByGroup": true,
"categoryOrder": ["Core", "Utilities", "Types", "*"],
"navigationLinks": {
"GitHub": "https://github.com/user/repo",
"npm": "https://www.npmjs.com/package/my-package"
},
"validation": {
"notExported": true,
"invalidLink": true,
"notDocumented": false
}
}
// package.json
{
"scripts": {
"docs": "typedoc",
"docs:watch": "typedoc --watch"
},
"devDependencies": {
"typedoc": "^0.25.0",
"typedoc-plugin-markdown": "^3.17.0",
"typedoc-plugin-mdn-links": "^3.1.0"
}
}
JSDoc Tags Reference
/**
* Summary description.
*
* @remarks
* Additional details and implementation notes.
*
* @param name - Parameter description
* @typeParam T - Type parameter description
* @returns Return value description
*
* @throws {ErrorType} When error condition
*
* @example
* ```typescript
* // Example code
* ```
*
* @see {@link RelatedItem} for related documentation
* @see https://example.com External link
*
* @deprecated Use `newFunction` instead
* @since 1.0.0
* @version 2.0.0
*
* @alpha - Early preview
* @beta - Feature complete but may change
* @public - Stable API
* @internal - Not for public use
* @readonly - Cannot be modified
* @virtual - Can be overridden
* @override - Overrides parent
* @sealed - Cannot be extended
*
* @defaultValue default value
* @eventProperty - For event properties
*/
Best Practices
- Document public API: All exports need docs
- Use examples: Show real usage
- Describe parameters: Clear, concise descriptions
- Document errors: What can be thrown
- Link related items: Use @see tags
- Keep updated: Sync docs with code
- Generate HTML: TypeDoc for browsable docs
- Validate in CI: Check for missing docs
Output Checklist
Every documented codebase should include:
- All public functions documented
- All interfaces and types documented
- All parameters described
- Return values documented
- Examples for complex functions
- Thrown errors documented
- TypeDoc configuration
- Generated documentation
- Documentation in CI pipeline
- README with API overview