@incidental/project-templates/templates/commands/shared/generate-docs.md

Claude Code template library for JavaScript projects with framework auto-detection

---
description: Generate documentation for code using JSDoc or TypeDoc
---

# Generate Documentation

Generate documentation for the project's code.

## Instructions

You are a documentation expert specializing in API documentation.

When the user requests documentation via $ARGUMENTS, follow these guidelines:

1. **Identify documentation needs:**
   - Check if project uses JSDoc, TypeDoc, or other tools
   - Determine which files need documentation
   - Look for existing documentation patterns

2. **For JSDoc (JavaScript):**
   ```javascript
   /**
    * Function description
    *
    * @param {string} name - The user's name
    * @param {number} age - The user's age
    * @returns {Object} User object with formatted data
    * @throws {Error} If name is empty
    *
    * @example
    * const user = createUser('John', 30)
    * console.log(user.name) // 'John'
    */
   function createUser(name, age) {
     if (!name) throw new Error('Name is required')
     return { name, age, createdAt: new Date() }
   }
   ```

3. **For TypeDoc (TypeScript):**
   ```typescript
   /**
    * User interface representing a system user
    *
    * @interface User
    */
   interface User {
     /** The user's unique identifier */
     id: string
     /** The user's display name */
     name: string
     /** The user's email address */
     email: string
   }

   /**
    * Creates a new user
    *
    * @param data - User data
    * @returns Promise resolving to created user
    *
    * @example
    * ```typescript
    * const user = await createUser({ name: 'John', email: 'john@example.com' })
    * ```
    */
   async function createUser(data: Partial<User>): Promise<User> {
     // Implementation
   }
   ```

4. **Documentation sections to include:**
   - Function/method description
   - Parameters with types and descriptions
   - Return value with type and description
   - Throws/errors that can occur
   - Usage examples
   - Related functions or types

5. **Generate README sections:**
   - If documenting a module, add README.md with:
     - Overview and purpose
     - Installation instructions
     - Usage examples
     - API reference
     - Contributing guidelines

6. **Best practices:**
   - Be concise but complete
   - Include examples for complex functions
   - Document edge cases and assumptions
   - Keep documentation up to date with code changes

7. **After generating docs:**
   - List which files were documented
   - Suggest running JSDoc/TypeDoc to generate HTML docs
   - Recommend setting up automated doc generation
   - Offer to create additional usage examples

**Target:** $ARGUMENTS (optional - specific file or module to document)