Documentation Generation

-- | Collect documentation from modules
collectDocs :: [Module] -> Either MultipleErrors [DocModule]

-- | Collect documentation with environment context
collectDocsWithEnv :: Environment -> [Module] -> Either MultipleErrors [DocModule]

-- | Documentation module representation
data DocModule = DocModule
  { dmName :: ModuleName
  , dmComments :: Maybe Text
  , dmDeclarations :: [DocDeclaration]
  , dmReExports :: [(InPackage ModuleName, [DocDeclaration])]
  }

-- | Documentation declaration
data DocDeclaration = DocDeclaration
  { declTitle :: Text
  , declComments :: Maybe Text
  , declSourceSpan :: Maybe SourceSpan
  , declChildren :: [ChildDeclaration]
  , declInfo :: DeclarationInfo
  , declKindInfo :: Maybe KindInfo
  }

-- | Generate HTML documentation
writeDocHtml :: DocModule -> Text

-- | Generate HTML documentation with options
writeDocHtmlWithOptions :: HtmlOptions -> DocModule -> Text

-- | HTML generation options
data HtmlOptions = HtmlOptions
  { htmlTitle :: Text
  , htmlCssUrl :: Maybe Text
  , htmlJsUrl :: Maybe Text
  , htmlHierarchyImages :: Bool
  , htmlUsePursuitLinks :: Bool
  , htmlSourceLinks :: Bool
  }

-- | Default HTML options
defaultHtmlOptions :: HtmlOptions

-- | Generate HTML index page
generateHtmlIndex :: [DocModule] -> Text

-- | Generate navigation HTML
generateNavigation :: [DocModule] -> Text

-- | Generate Markdown documentation
writeDocMarkdown :: DocModule -> Text

-- | Generate Markdown with options
writeDocMarkdownWithOptions :: MarkdownOptions -> DocModule -> Text

-- | Markdown generation options
data MarkdownOptions = MarkdownOptions
  { markdownTitle :: Text
  , markdownGithubSourceLinks :: Bool
  , markdownPursuitLinks :: Bool
  , markdownTableOfContents :: Bool
  }

-- | Default Markdown options
defaultMarkdownOptions :: MarkdownOptions

-- | Generate Markdown table of contents
generateTOC :: DocModule -> Text

-- | Generate Markdown for declaration
declToMarkdown :: DocDeclaration -> Text

-- | Render type for documentation
renderDocType :: SourceType -> RenderedCode

-- | Render constraint for documentation
renderDocConstraint :: SourceConstraint -> RenderedCode

-- | Render value signature
renderDocValue :: Ident -> SourceType -> RenderedCode

-- | Rendered code with syntax highlighting
data RenderedCode = RenderedCode
  { rcodeText :: Text
  , rcodeAnnotations :: [CodeAnnotation]
  }

-- | Code annotations for syntax highlighting
data CodeAnnotation = CodeAnnotation
  { caStart :: Int
  , caEnd :: Int
  , caType :: AnnotationType
  , caData :: Maybe Text
  }

-- | Annotation types
data AnnotationType
  = AnnKeyword | AnnType | AnnConstructor | AnnFunction | AnnComment | AnnString

-- | Extract documentation comments
extractDocComments :: [Comment] -> Maybe Text

-- | Process documentation comment text
processDocComment :: Text -> Text

-- | Attach comments to declarations
attachComments :: [Comment] -> [Declaration] -> [Declaration]

-- | Comment attachment rules
data CommentRule
  = AttachToNext        -- Attach to following declaration
  | AttachToPrevious    -- Attach to previous declaration
  | StandaloneComment   -- Keep as standalone

-- | Determine comment attachment
determineAttachment :: Comment -> [Declaration] -> CommentRule

-- | Generate cross-reference links
generateCrossRefs :: [DocModule] -> [DocModule]

-- | Cross-reference information
data CrossRef = CrossRef
  { crSource :: SourceSpan
  , crTarget :: Qualified Ident
  , crKind :: CrossRefKind
  }

-- | Cross-reference kinds
data CrossRefKind
  = LinkToValue | LinkToType | LinkToConstructor | LinkToClass | LinkToModule

-- | Resolve cross-reference
resolveCrossRef :: Environment -> CrossRef -> Maybe DocLink

-- | Documentation link
data DocLink = DocLink
  { dlText :: Text
  , dlUrl :: Text
  , dlTitle :: Maybe Text
  }

-- | Generate type class hierarchy
generateHierarchy :: [DocModule] -> HierarchyGraph

-- | Type class hierarchy graph
data HierarchyGraph = HierarchyGraph
  { hgNodes :: [HierarchyNode]
  , hgEdges :: [HierarchyEdge]
  }

-- | Hierarchy node (type class)
data HierarchyNode = HierarchyNode
  { hnName :: Qualified (ProperName 'ClassName)
  , hnKind :: SourceKind
  , hnFunctionalDependencies :: [FunctionalDependency]
  , hnMembers :: [Ident]
  }

-- | Hierarchy edge (superclass relationship)
data HierarchyEdge = HierarchyEdge
  { heSuperclass :: Qualified (ProperName 'ClassName)
  , heSubclass :: Qualified (ProperName 'ClassName)
  , heConstraint :: SourceConstraint
  }

-- | Generate GraphViz DOT format
hierarchyToDot :: HierarchyGraph -> Text

-- | Generate SVG hierarchy diagram
hierarchyToSvg :: HierarchyGraph -> Text

-- | Generate search index
generateSearchIndex :: [DocModule] -> SearchIndex

-- | Search index data
data SearchIndex = SearchIndex
  { siEntries :: [SearchEntry]
  , siMetadata :: SearchMetadata
  }

-- | Search entry
data SearchEntry = SearchEntry
  { seTitle :: Text
  , seType :: Maybe Text
  , seModule :: ModuleName
  , sePackage :: Maybe Text
  , seComments :: Maybe Text
  , seKind :: SearchKind
  }

-- | Search kinds
data SearchKind
  = SearchValue | SearchType | SearchConstructor | SearchClass | SearchModule

-- | Search index metadata
data SearchMetadata = SearchMetadata
  { smVersion :: Text
  , smGenerated :: UTCTime
  , smPackages :: [Text]
  }

-- | Serialize search index to JSON
searchIndexToJson :: SearchIndex -> Value

-- | Generate ctags format
generateCtags :: [DocModule] -> Text

-- | Generate etags format  
generateEtags :: [DocModule] -> Text

-- | Tag entry
data TagEntry = TagEntry
  { teTag :: Text
  , teFile :: FilePath
  , teAddress :: TagAddress
  , teKind :: TagKind
  , teFields :: [(Text, Text)]
  }

-- | Tag address (line number or pattern)
data TagAddress = LineNumber Int | SearchPattern Text

-- | Tag kinds
data TagKind = TagFunction | TagType | TagConstructor | TagClass | TagModule

-- | Convert DocDeclaration to tags
declToTags :: FilePath -> DocDeclaration -> [TagEntry]

-- | Validate documentation completeness
validateDocs :: [DocModule] -> Either [DocError] ()

-- | Documentation validation errors
data DocError
  = MissingDocumentation Ident
  | InvalidCrossReference Text
  | MalformedComment Text
  | InconsistentTypeSignature Ident SourceType SourceType

-- | Check for missing documentation
checkMissingDocs :: DocModule -> [DocError]

-- | Validate cross-references
validateCrossRefs :: [DocModule] -> [DocError]

-- | Check documentation coverage
calculateCoverage :: DocModule -> DocCoverage

-- | Documentation coverage statistics
data DocCoverage = DocCoverage
  { dcTotal :: Int
  , dcDocumented :: Int
  , dcPercentage :: Double
  }

-- | Multi-package documentation
data PackageDocs = PackageDocs
  { pdPackage :: PackageInfo
  , pdModules :: [DocModule]
  , pdDependencies :: [PackageInfo]
  }

-- | PackageInfo
data PackageInfo = PackageInfo
  { piName :: Text
  , piVersion :: Text
  , piHomepage :: Maybe Text
  , piRepository :: Maybe Text
  }

-- | Generate multi-package documentation
generatePackageDocs :: [PackageDocs] -> Text

-- | Cross-package reference resolution
resolveCrossPackageRefs :: [PackageDocs] -> [PackageDocs]

-- | Generate package index
generatePackageIndex :: [PackageDocs] -> Text

-- | Declaration information
data DeclarationInfo
  = ValueDeclaration (Maybe SourceType)
  | DataDeclaration DataDeclType [TypeParameter] [(ProperName 'ConstructorName, [SourceType])]
  | ExternDataDeclaration SourceKind
  | TypeSynonymDeclaration [TypeParameter] SourceType
  | TypeClassDeclaration [TypeParameter] [SourceConstraint] [FunctionalDependency] [Ident]
  | AliasDeclaration Ident
  | ExternKindDeclaration
  | RoleDeclaration [Role]

-- | Kind information
data KindInfo = KindInfo
  { kiKind :: SourceKind
  , kiConstraints :: [SourceConstraint]
  }

-- | Child declaration
data ChildDeclaration = ChildDeclaration
  { cdeclTitle :: Text
  , cdeclComments :: Maybe Text
  , cdeclSourceSpan :: Maybe SourceSpan
  , cdeclInfo :: DeclarationInfo
  }

-- | Type parameter documentation
data TypeParameter = TypeParameter
  { tpName :: Text
  , tpKind :: Maybe SourceKind
  , tpDescription :: Maybe Text
  }

-- | Documentation output format
data DocFormat
  = HtmlFormat HtmlOptions
  | MarkdownFormat MarkdownOptions
  | CtagsFormat
  | EtagsFormat
  | JsonFormat

-- | Generate documentation in specified format
generateDocs :: DocFormat -> [DocModule] -> Text

-- | Multiple format generation
generateMultiFormat :: [DocFormat] -> [DocModule] -> [(DocFormat, Text)]

-- | Documentation generation result
data DocResult = DocResult
  { drFormat :: DocFormat
  , drContent :: Text
  , drFiles :: [(FilePath, Text)]  -- Additional files (CSS, JS, etc.)
  }

-- | Documentation theme
data DocTheme = DocTheme
  { dtName :: Text
  , dtCss :: Text
  , dtJs :: Maybe Text
  , dtFavicon :: Maybe Text
  }

-- | Built-in themes
defaultTheme :: DocTheme
darkTheme :: DocTheme  
minimalistTheme :: DocTheme

-- | Apply theme to HTML documentation
applyTheme :: DocTheme -> Text -> Text

-- | Custom CSS injection
injectCustomCss :: Text -> Text -> Text