nextjs-tsdoc-documentor

What this skill does

• Adds TSDoc comments to all TypeScript functions in Next.js projects
• Ensures all functions with parameters have proper @param tags with type information
• Documents return values with @returns tags
• Handles async functions, React components, and utility functions
• Maintains existing TSDoc style conventions in the codebase
• Follows TSDoc standards for TypeScript code documentation
• Integrates with TypeScript's type system for better IDE support

When to use

Use this when:

• Implementing new functions, components, or utility modules in Next.js TypeScript projects
• Refactoring code and adding missing documentation
• Preparing for code review and ensuring proper TSDoc documentation standards
• Functions lack TSDoc comments or have incomplete parameter documentation
• You need to enforce TSDoc presence as part of quality checks

Common signals:

• TypeScript functions without TSDoc comments
• Functions with parameters but missing @param tags
• Return values not documented with @returns
• Async functions without proper @returns Promise<T> documentation
• TypeScript code lacking type-aware documentation

TSDoc Standard Format

Basic Function

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

Async Function

/**
 * Fetch user data from the API.
 *
 * @param userId - The unique identifier of user
 * @returns A promise that resolves to the user data
 * @throws When the API request fails
 */
async function fetchUser(userId: string): Promise<User> {
  const response = await fetch(`/api/users/${userId}`);
  if (!response.ok) {
    throw new Error('Failed to fetch user');
  }
  return response.json();
}

React Component

/**
 * UserProfile component displays user information.
 *
 * @param props - Component properties
 * @param props.userId - The user's unique identifier
 * @param props.onEdit - Callback when edit button is clicked
 * @returns A React component rendering user profile
 */
export function UserProfile({ userId, onEdit }: UserProfileProps) {
  // Component implementation
}