Documentation

Documentation (TypeScript + React)

Generate comprehensive documentation for features, components, and hooks.

When to Use

• After completing a feature (may span multiple commits)
• When a component/hook needs usage documentation
• When design decisions need recording
• For public/shared components and hooks

Documentation Types

1. Storybook Stories (Component Documentation)

Purpose: Visual documentation of component usage and variants

Creates: .stories.tsx files alongside components

2. JSDoc Comments (Code Documentation)

Purpose: Inline documentation for types, props, complex functions

Location: In source files (.ts, .tsx)

3. Feature Documentation (Architectural Documentation)

Purpose: WHY decisions were made, HOW feature works, WHAT to extend

Creates: docs/features/[feature-name].md

Workflow

1. Identify Documentation Needs

Ask:

• Is this a reusable component? → Storybook story
• Is this a custom hook? → JSDoc + usage example
• Is this a complete feature? → Feature documentation
• Are types/props complex? → JSDoc comments

2. Create Storybook Stories

For each component, create stories showing:

• Default state
• All variants/props
• Interactive states
• Edge cases (loading, error, empty)

Example:

// src/components/Button/Button.stories.tsx
import type { Meta, StoryObj } from '@storybook/react'
import { Button } from './Button'

const meta: Meta<typeof Button> = {
  title: 'Components/Button',
  component: Button,
  parameters: {
    layout: 'centered'
  },
  tags: ['autodocs'],
  argTypes: {
    variant: {
      control: 'select',
      options: ['primary', 'secondary', 'danger']
    }
  }
}

export default meta
type Story = StoryObj<typeof Button>

// Default story
export const Primary: Story = {
  args: {
    label: 'Button',
    variant: 'primary',
    onClick: () => alert('clicked')
  }
}

// Variants
export const Secondary: Story = {
  args: {
    ...Primary.args,
    variant: 'secondary'
  }
}

export const Danger: Story = {
  args: {
    ...Primary.args,
    variant: 'danger'
  }
}

// States
export const Disabled: Story = {
  args: {
    ...Primary.args,
    isDisabled: true
  }
}

export const Loading: Story = {
  args: {
    ...Primary.args,
    isLoading: true
  }
}

// Interactive example
export const WithIcon: Story = {
  args: {
    ...Primary.args,
    icon: <IconCheck />
  }
}

3. Add JSDoc Comments

For public types and interfaces:

/**
 * Props for the Button component.
 *
 * @example
 * ```tsx
 * <Button
 *   label="Click me"
 *   variant="primary"
 *   => console.log('clicked')}
 * />
 * ```
 */
export interface ButtonProps {
  /** The text to display on the button */
  label: string

  /** The visual style variant of the button */
  variant?: 'primary' | 'secondary' | 'danger'

  /** Callback fired when the button is clicked */
  onClick: () => void

  /** If true, the button will be disabled */
  isDisabled?: boolean

  /** If true, the button will show a loading spinner */
  isLoading?: boolean
}

For custom hooks:

/**
 * Custom hook for managing user authentication state.
 *
 * Handles login, logout, and persisting auth state to localStorage.
 * Automatically refreshes token when it expires.
 *
 * @param options - Configuration options for authentication
 * @returns Authentication state and methods
 *
 * @example
 * ```tsx
 * function LoginForm() {
 *   const { login, isLoading, error } = useAuth()
 *
 *   const handleSubmit = async (email: string, password: string) => {
 *     await login(email, password)
 *   }
 *
 *   return <Form isLoading={isLoading} error={error} />
 * }
 * ```
 */
export function useAuth(options?: AuthOptions): UseAuthReturn {
  // Implementation
}

For complex types:

/**
 * Represents the state of an asynchronous operation.
 *
 * Uses discriminated union to ensure invalid states are impossible
 * (e.g., cannot have both data and error simultaneously).
 *
 * @template T - The type of data returned on success
 *
 * @example
 * ```typescript
 * const [state, setState] = useState<AsyncState<User>>({ status: 'idle' })
 *
 * // Type narrowing works automatically
 * if (state.status === 'success') {
 *   console.log(state.data.name) // state.data is available and typed
 * }
 * ```
 */
export type AsyncState<T> =
  | { status: 'idle' }
  | { status: 'loading' }
  | { status: 'success'; data: T }
  | { status: 'error'; error: Error }

4. Create Feature Documentation

For completed features, create docs/features/[feature-name].md:

Template:

# Feature: [Feature Name]

## Overview
Brief description of what the feature does and why it exists.

## Problem
What problem does this feature solve? What was the pain point?

## Solution
How does this feature solve the problem? What approach was taken?

## Architecture

### Components
- **ComponentName**: Purpose and responsibility
- **AnotherComponent**: Purpose and responsibility

### Hooks
- **useFeatureHook**: What it does and why it's separate

### Context
- **FeatureContext**: What state it manages and why context was needed

### Types
- **KeyType**: What it represents and why it's a custom type

## Key Design Decisions

### 1. [Decision Title]
**Decision**: What was decided
**Rationale**: Why this approach was chosen
**Alternatives**: What other approaches were considered
**Trade-offs**: What we gained and what we gave up

### 2. [Another Decision]
...

## Usage

### Basic Usage
```typescript
// Simple example showing most common use case

Advanced Usage

// Example showing advanced features or edge cases

Integration

How this feature integrates with other parts of the application.

API Reference

Components

ComponentName

Props:

• propName (Type): Description

Events:

• onEvent: When it fires and what it provides

AnotherComponent

...

Hooks

useFeatureHook

Parameters:

• param (Type): Description

Returns:

• returnValue (Type): Description

Types

TypeName

type TypeName = ...

Description of when and how to use this type.

Testing Strategy

Unit Tests

• What is tested at the unit level (pure components, hooks)
• Coverage expectations (100% for leaf components)

Integration Tests

• What user flows are tested
• How mocking is handled (MSW for APIs)

Accessibility

Compliance

• WCAG level compliance (A, AA, AAA)
• What accessibility features are implemented

Keyboard Navigation

• What keyboard shortcuts are supported
• How tab order works

Screen Reader Support

• What ARIA attributes are used
• What announcements are made

Performance Considerations

Optimizations

• What performance optimizations are implemented
• Use of memo, useMemo, useCallback

Bundle Impact

• Approximate bundle size contribution
• Any lazy loading or code splitting

Known Limitations

Current Limitations

• What doesn't work yet
• What edge cases aren't handled

Future Enhancements

• What could be improved
• What features could be added

Troubleshooting

Common Issues

Issue: [Problem Description]

Symptom: What users will see Cause: Why this happens Solution: How to fix it

Related Features

• Links to related documentation
• Dependencies on other features
• Features that depend on this

Migration Guide

(If replacing existing functionality)

Before

// Old way

After

// New way

Breaking Changes

• What changed
• How to update code

Changelog

• v1.1.0 (2024-01-15): Added support for...
• v1.0.0 (2024-01-01): Initial implementation

## Output Format

After generating documentation:

📚 DOCUMENTATION GENERATED

Feature: User Authentication

Generated Files: ✅ Storybook Stories (3 components)

• src/features/auth/components/LoginForm.stories.tsx
• src/features/auth/components/RegisterForm.stories.tsx
• src/features/auth/components/PasswordInput.stories.tsx

✅ JSDoc Comments Added

• src/features/auth/hooks/useAuth.ts (hook documentation)
• src/features/auth/types.ts (type definitions)
• src/features/auth/context/AuthContext.tsx (context API)

✅ Feature Documentation

• docs/features/authentication.md (complete guide)

📖 Documentation includes:

• Problem/solution overview
• Architecture and design decisions
• Usage examples (basic + advanced)
• API reference (components, hooks, types)
• Testing strategy
• Accessibility features
• Performance considerations
• Troubleshooting guide

🎯 Next Steps:

1. Review generated Storybook stories locally: npm run storybook
2. Review feature documentation: docs/features/authentication.md
3. Update any project-specific references or links
4. Commit documentation with feature code

📝 Maintenance:

• Update Storybook stories when component props change
• Update JSDoc when APIs change
• Update feature docs when design decisions change
• Keep examples working (they're testable!)

## Documentation Principles

### For Humans AND AI

Documentation serves two audiences:
1. **Human developers**: Need to understand and extend code
2. **AI assistants**: Need context to help debug and extend features

Write documentation that helps both audiences understand:
- **WHY** decisions were made (context for future changes)
- **HOW** the feature works (architecture and flow)
- **WHAT** can be extended (integration points)

### Show, Don't Tell

Prefer code examples over prose descriptions:

**❌ Bad**:

The Button component accepts a variant prop that can be primary, secondary, or danger, and will style the button accordingly.

**✅ Good**:
```typescript
<Button variant="primary" label="Save" />
<Button variant="secondary" label="Cancel" />
<Button variant="danger" label="Delete" />

Keep Examples Executable

Storybook stories and JSDoc examples should be real, working code that compiles and runs.

Document Design Decisions

Most important: WHY decisions were made.

❌ Bad:

// Uses context for state management

✅ Good:

/**
 * Uses AuthContext for state management instead of prop drilling.
 *
 * Decision: Context chosen because auth state is needed in 10+
 * components across different nesting levels (nav, profile, settings,
 * protected routes). Prop drilling would be unmaintainable.
 *
 * Alternative considered: Redux - overkill for single feature state
 */

When to Document

Always Document

• Public/shared components
• Custom hooks (except trivial ones)
• Complex types (discriminated unions, branded types)
• Completed features (spanning multiple commits)

Consider Documenting

• Complex utility functions
• Non-obvious algorithms
• Performance-critical code
• Edge cases and workarounds

Don't Over-Document

• Trivial functions (self-explanatory)
• Implementation details (private functions)
• Obvious code (const user = getUser())

Best Practices

Storybook

• One story file per component
• Show all variants
• Include interactive controls
• Document props with argTypes
• Add accessibility checks (a11y addon)

JSDoc

• Use @param, @returns, @example tags
• Include examples showing typical usage
• Document complex types inline
• Link related types with @see

Feature Docs

• Start with problem/solution
• Include architecture diagrams (mermaid)
• Provide working code examples
• Document WHY, not just WHAT
• Keep updated as feature evolves

Tools

Storybook Commands

# Run Storybook locally
npm run storybook

# Build static Storybook
npm run build-storybook

# Test stories (interaction testing)
npm run test-storybook

TypeDoc (Alternative to JSDoc)

# Generate API documentation from TypeScript
npx typedoc --entryPoints src/index.ts

Key Principles

See reference.md for detailed principles:

• Document WHY, not just WHAT
• Show working code examples
• Keep docs close to code
• Update docs with code changes
• Test examples (Storybook)
• Document for humans AND AI
• Focus on usage, not implementation

See reference.md for complete documentation templates and examples.

Acceptance Criteria

All criteria must be met before documentation is considered complete.

Mandatory Requirements (Must Pass)

1. JSDoc Comments (for hooks and types)

   • All public hooks have JSDoc with @example
   • All complex types have JSDoc explanations
   • Props interfaces documented
   • Return types documented for hooks

2. Examples Are Executable

   • JSDoc examples are valid TypeScript
   • Code examples compile without errors

3. Documentation Quality

   • WHY documented, not just WHAT
   • Examples show typical usage patterns
   • Integration points described
   • Troubleshooting section for complex features

Nice-to-Have (Optional)

1. Storybook Stories (for components)
   • Story file created for each public component
   • Default state story exists
   • All variants/props demonstrated
   • Interactive states shown (loading, error, empty)
   • Stories compile and render without errors

Note: Storybook is valuable for visual documentation but not required for skill completion.

Documentation Completion Checklist

✅ DOCUMENTATION ACCEPTANCE CRITERIA

JSDoc (Hooks & Types) - REQUIRED:
[ ] Public hooks documented
[ ] @example tags with working code
[ ] Complex types explained
[ ] Return types documented

Quality - REQUIRED:
[ ] WHY, not just WHAT
[ ] Examples are executable
[ ] Integration points clear
[ ] Troubleshooting included (for complex features)

Storybook (Components) - OPTIONAL:
[ ] Story file per public component
[ ] Default state story
[ ] All variants shown
[ ] Edge cases covered (loading, error, empty)

Documentation complete: All REQUIRED boxes checked ✅

What Blocks Completion

The following will BLOCK documentation completion:

• Missing JSDoc for public hooks
• Examples that don't compile
• Documentation that only describes WHAT (not WHY)

The following will NOT block completion:

• Missing Storybook stories (nice-to-have)

Documentation Output Requirements

Documentation must include:

1. JSDoc Comments - Inline documentation for hooks and types (required)
2. Working Examples - All examples must compile (required)
3. Storybook Stories - Visual documentation for components (optional, nice-to-have)

Documentation Types by Scope