import { DocSuggestion } from '../entities/DocSuggestion';
import { CodeBlock } from '../entities/CodeBlock';

export interface DocumentationOptions {
  readonly format: 'markdown' | 'jsdoc' | 'tsdoc' | 'asciidoc' | 'rst' | 'plain';
  readonly language: string;
  readonly includeExamples?: boolean;
  readonly includeParameters?: boolean;
  readonly includeReturnTypes?: boolean;
  readonly includeSeeAlso?: boolean;
  readonly style?: 'formal' | 'casual' | 'technical' | 'beginner';
}

export interface DocumentationPort {
  /**
   * Generate documentation for a code block
   */
  generateDocumentation(
    codeBlock: CodeBlock,
    options: DocumentationOptions
  ): Promise<DocSuggestion[]>;

  /**
   * Generate documentation for multiple code blocks
   */
  generateDocumentationForMultiple(
    codeBlocks: CodeBlock[],
    options: DocumentationOptions
  ): Promise<DocSuggestion[]>;

  /**
   * Generate API documentation
   */
  generateApiDocumentation(
    codeBlocks: CodeBlock[],
    options: DocumentationOptions
  ): Promise<DocSuggestion[]>;

  /**
   * Generate README documentation
   */
  generateReadmeDocumentation(
    projectInfo: {
      readonly name: string;
      readonly description: string;
      readonly language: string;
      readonly features: string[];
      readonly installation: string;
      readonly usage: string;
    },
    options: DocumentationOptions
  ): Promise<DocSuggestion[]>;

  /**
   * Generate changelog documentation
   */
  generateChangelog(
    commits: Array<{
      readonly hash: string;
      readonly message: string;
      readonly date: Date;
      readonly author: string;
    }>,
    options: DocumentationOptions
  ): Promise<DocSuggestion[]>;

  /**
   * Generate architecture documentation
   */
  generateArchitectureDocumentation(
    codeBlocks: CodeBlock[],
    options: DocumentationOptions
  ): Promise<DocSuggestion[]>;

  /**
   * Validate documentation quality
   */
  validateDocumentation(
    documentation: string,
    codeBlock: CodeBlock
  ): Promise<{
    readonly isValid: boolean;
    readonly issues: Array<{
      readonly type: 'error' | 'warning' | 'suggestion';
      readonly message: string;
      readonly line?: number;
    }>;
  }>;

  /**
   * Extract documentation from existing code
   */
  extractExistingDocumentation(
    codeBlocks: CodeBlock[]
  ): Promise<DocSuggestion[]>;
}