What problem does it solve? Doc comments sit next to code but nothing compiles them, so they drift silently: parameters get renamed, return types change, and copied blocks document the wrong method. Because the code still works, stale documentation is trusted far longer than it should be, and bloated comment blocks add reading cost to every file. ## Core Features & Use Cases - Signature Drift Detection: Parses every declaration in scope and mechanically verifies each documented name, @param, @return, and @throws against the real signature, auto-fixing provable mismatches. - Eleven-Class Defect Taxonomy: Classifies each block as signature drift, clone drift, contradiction, tautology, history, ticket reference, body restatement, oversized, orphaned, tombstone, or load-bearing, with distinct actions per class. - Prioritized Bloat Sweeps: Scores and ranks blocks and files by targetable lines so a bounded pass on a large codebase captures most of the win and names exactly what was left. - Use Case: Before publishing API reference docs (javadoc, typedoc, sphinx, DocC), run the audit on the modules a release touches to fix wrong parameter names, strip ticket IDs and design archaeology, and compress oversized blocks while preserving load-bearing constraints. ## Quick Start Ask the assistant to run ar-optimize-doc-comments on a module or the current PR diff to audit the doc comments and fix signature drift.
