📚 Add comprehensive code documentation (JSDoc)

[ryota-murakami]

Problem

The codebase lacks comprehensive documentation, making it difficult for contributors to understand function purposes, parameters, and return values. Currently, there are zero JSDoc comments in index.js and minimal inline documentation.

Impact:

• New contributors struggle to understand code
• IDE type hints and autocomplete don't work
• Function contracts are unclear
• Maintenance is more difficult
• Higher risk of bugs from misunderstanding code

Current State

// index.js - No documentation
export async function getGitSummary() {
  try {
    // ...389 lines with only 1 comment
  }
}

const gptCommit = async () => {
  // No documentation about what this does, parameters, or return value
}

Proposed Solution

1. Add JSDoc Comments to All Functions

Example: getGitSummary()

/**
 * Retrieves the git diff summary of staged changes
 * Automatically excludes lock files (package-lock.json, yarn.lock, pnpm-lock.yaml)
 * Initializes OpenAI client if API key is available
 * 
 * @async
 * @returns {Promise<string|null>} Git diff output or null if no staged changes
 * @throws {Error} If OpenAI API key is missing
 * @throws {Error} If git command fails
 * 
 * @example
 * const diff = await getGitSummary()
 * if (diff) {
 *   console.log('Changes detected:', diff.length, 'characters')
 * }
 */
export async function getGitSummary() {
  try {
    // If no API key in config, try to load from .env
    if (!apiKey) {
      const dotenv = await import('dotenv')
      const envPath = path.join(process.cwd(), '.env')
      dotenv.config({ path: envPath })
    }

    // Use API key from config if available, otherwise use from .env
    const openaiApiKey = apiKey || process.env.OPENAI_API_KEY

    if (!openaiApiKey) {
      console.error(
        'No OpenAI API key found. Please set it using "git gpt open-api-key add".',
      )
      process.exit(1)
    }

    openai = new OpenAI({ apiKey: openaiApiKey })

    const exec = promisify(originalExec)
    const { stdout } = await exec(
      "git diff --cached -- . ':(exclude)*lock.json' ':(exclude)*lock.yaml'",
    )
    const summary = stdout.trim()
    if (summary.length === 0) {
      return null
    }

    return summary
  } catch (error) {
    console.error('Error while summarizing Git changes:', error)
    process.exit(1)
  }
}

Example: gptCommit()

/**
 * Generates an AI-powered commit message and commits changes
 * 
 * Workflow:
 * 1. Gets git diff of staged changes
 * 2. Sends diff to OpenAI API with configured model and language
 * 3. Sanitizes the generated commit message
 * 4. Prompts user for confirmation
 * 5. Commits with the message if confirmed
 * 
 * @async
 * @returns {Promise<void>}
 * @throws {Error} If OpenAI API call fails
 * @throws {Error} If git commit fails
 * 
 * @example
 * await gptCommit()
 * // Prompts user and commits if changes exist
 */
const gptCommit = async () => {
  const gitSummary = await getGitSummary()
  if (!gitSummary) {
    console.log('No changes to commit. Commit canceled.')
    process.exit(0)
  }

  // ... rest of implementation
}

Example: loadConfig()

/**
 * Loads user configuration from ~/.git-gpt-commit-config.json
 * Updates global state with saved preferences
 * Continues with defaults if config file doesn't exist or is corrupted
 * 
 * Configuration options:
 * - model: OpenAI model to use (default: 'gpt-5-mini')
 * - language: Commit message language (default: 'English')
 * - prefixEnabled: Use conventional commit prefixes (default: true)
 * - apiKey: OpenAI API key (optional, can use .env instead)
 * 
 * @returns {void}
 * 
 * @example
 * loadConfig()
 * console.log('Using model:', model)
 */
function loadConfig() {
  try {
    if (fs.existsSync(CONFIG_FILE)) {
      const config = JSON.parse(fs.readFileSync(CONFIG_FILE, 'utf8'))
      if (config.model) {
        model = config.model
      }
      if (config.language) {
        language = config.language
      }
      if (config.prefixEnabled !== undefined) {
        prefixState.setEnabled(config.prefixEnabled)
      }
      if (config.apiKey) {
        apiKey = config.apiKey
      }
    }
  } catch (error) {
    console.error('Error loading configuration:', error)
    // Continue with default model if there's an error
  }
}

2. Add Inline Comments for Complex Logic

// Example: Prefix state management
const prefixState = (() => {
  // Use closure pattern to encapsulate state
  // This prevents direct mutation from outside
  let enabled = true // Default is enabled
  return {
    /**
     * Checks if conventional commit prefixes are enabled
     * @returns {boolean} True if prefixes should be used
     */
    isEnabled: () => enabled,
    
    /**
     * Enables or disables conventional commit prefixes
     * @param {boolean} value - True to enable, false to disable
     * @returns {boolean} The new value
     */
    setEnabled: (value) => {
      enabled = value
      return value
    },
  }
})()

3. Document Complex Prompts

const messages = [
  {
    role: 'system',
    content:
      // System prompt that guides the AI's behavior
      // Key requirements:
      // 1. Semantic messages (explain PURPOSE and IMPACT)
      // 2. Focus on WHY, not just WHAT
      // 3. Respect configured language
      // 4. Keep under 72 characters for subject line
      'You are an expert Git commit message writer. Generate semantic, meaningful commit messages that explain the PURPOSE and IMPACT of changes, not just what changed. ' +
      'Focus on WHY the change was made and its benefits. Write in ' +
      language +
      '. Keep messages concise but descriptive, under 72 characters for the subject line.',
  },
  // ... rest of messages
]

4. Create Type Definitions (Optional)

/**
 * @typedef {Object} Config
 * @property {string} model - OpenAI model name
 * @property {string} language - Commit message language
 * @property {boolean} prefixEnabled - Use conventional commit prefixes
 * @property {string} [apiKey] - OpenAI API key (optional)
 */

/**
 * @typedef {Object} OpenAIMessage
 * @property {'system'|'user'|'assistant'} role - Message role
 * @property {string} content - Message content
 */

/**
 * @param {Config} config - Configuration object
 * @returns {void}
 */
function saveConfig(config) {
  // ...
}

Documentation Standards

Function Documentation Template

/**
 * Brief one-line description
 * 
 * Detailed description (optional):
 * - Key behavior
 * - Important notes
 * - Edge cases
 * 
 * @async (if applicable)
 * @param {Type} paramName - Parameter description
 * @param {Type} [optionalParam] - Optional parameter description
 * @returns {ReturnType} Return value description
 * @throws {ErrorType} When this error occurs
 * 
 * @example
 * // Usage example
 * const result = functionName(param)
 */

Inline Comment Guidelines

• Explain WHY, not WHAT (code shows what)
• Document complex algorithms
• Note non-obvious behavior
• Explain workarounds or hacks
• Reference issue numbers for context

Benefits

• ✅ Better IDE support (autocomplete, type hints)
• ✅ Easier onboarding for new contributors
• ✅ Clearer function contracts
• ✅ Reduced maintenance burden
• ✅ Better code understanding
• ✅ Self-documenting code

Acceptance Criteria

• Add JSDoc comments to all exported functions
• Add JSDoc comments to all major internal functions
• Add inline comments for complex logic (>10 lines)
• Document all configuration options
• Add @example tags for public API functions
• Create type definitions for key data structures
• Generate .d.ts files (optional, using JSDoc)
• Update CLAUDE.md with documentation standards

Priority

Medium - Improves maintainability and contributor experience

Related

Quality analysis report: claudedocs/quality-analysis-report.md section 8

Tools

Consider using:

• documentation.js for generating API docs
• TypeDoc if adding .d.ts files
• ESLint plugin for enforcing JSDoc (eslint-plugin-jsdoc)