Refactoring Plan: Modular OOP & SOLID Architecture

This document describes the architectural transition of the Universal Documentation Engine (UDE) from a monolithic, conditional-heavy MVP implementation into a modular, highly cohesive, and SOLID-compliant design system.

---

🗺️ Architectural Target Design

---

🗓️ Refactoring Milestones

📍 Phase 1: Base Parsing Layer Extraction (BaseDoxygenParser)

• Goal: Isolate Doxygen XML file reading, catalog tree assembling, and generic node parsing from language-specific logic.
• Tasks:
  1. Define BaseDoxygenParser(BaseParser) in ude/parsers/base.py.
  2. Implement shared XML navigation helper methods (_find_nodes, _parse_common_blocks, _extract_brief).
  3. Move metadata storage, logging initialization, and XML parsing loop orchestration to the base class.

📍 Phase 2: Concrete Language-Specific Parsers Extraction

• Goal: Isolate language-specific parsing constraints into individual, highly cohesive classes.
• Tasks:
  1. Implement CppDoxygenParser(BaseDoxygenParser):
     • Handle double-colon (::) scoping.
     • Strip export/linkage macros (REQ-FUN-19).
     • Escape angle brackets (< >) for C++ templates (REQ-FUN-02).
  2. Implement CsharpDoxygenParser(BaseDoxygenParser):
     • Handle C# dot namespace resolution.
     • Filter SWIG internal boilerplate (swigCPtr, Dispose) (REQ-FUN-20).
     • Apply C# pointer type cleaning mapping (REQ-FUN-40).
  3. Implement JavaDoxygenParser(BaseDoxygenParser):
     • Parse Javadoc parameters and packages.
     • Filter SWIG internal boilerplate (REQ-FUN-20).
     • Apply Java pointer type cleaning mapping (REQ-FUN-40).
  4. Implement PythonDoxygenParser(BaseDoxygenParser):
     • Filter SWIG internal boilerplate (REQ-FUN-20).
     • Parse Sphinx/RST comment structures (REQ-FUN-14).
     • Reconstruct dynamic function signatures and map parameter types from docstrings.
  5. Build DoxygenParserFactory to dynamically resolve and instantiate the target parser based on the config.

📍 Phase 3: Layout Signature Formatters (Strategy Pattern)

• Goal: Decouple visual rendering code from raw signature compilation.
• Tasks:
  1. Define the SignatureFormatter abstract interface.
  2. Implement CppSignatureFormatter, CsharpSignatureFormatter, JavaSignatureFormatter, and PythonSignatureFormatter.
  3. Relocate type delimiter transformations (:: to .) and class declaration text generation from HTML/Markdown templates into the formatters.

📍 Phase 4: Specializing Templates & Upgrading Renderers

• Goal: Simplify template structures by removing nested conditional blocks ({% if language %}).
• Tasks:
  1. Structure the template layouts into specialized subdirectories:
     • ude/templates/common/ (Shared styles and scripts).
     • ude/templates/cpp/ (C++ specific layout).
     • ude/templates/csharp/ (C# specific layout).
     • ude/templates/java/ (Java specific layout).
     • ude/templates/python/ (Python specific layout).
  2. Update HtmlRenderer and HugoMarkdownRenderer to load the appropriate template dynamically based on language config.
  3. Inject the designated SignatureFormatter instance into Jinja2 templates, replacing complex conditional markup with simple, clean method calls: {{ formatter.format_class_prototype(entity) }}.

---

🛡️ Regression Testing & Quality Gates

To guarantee that the refactoring is 100% safe and introduces zero behavioral bugs or broken layouts:

1. Unit Test Alignment:

   • Refactor existing test suites (tests/test_doxygen_parser.py) to verify that the split language-specific parsers handle their designated tasks independently.
   • Maintain a strict total statement coverage target of >= 98% using pytest-cov.

2. Snapshot Testing (Golden Master / Sandbox):

   • Prior to refactoring, compile documentation for all 11 test reference projects and save the entire generated ude_output/ output structure as a "Golden Master" reference snapshot.
   • Post-refactoring, re-compile the identical targets and execute a recursive automated file-by-file text comparison (using a custom python script or diff -r) to guarantee that the generated HTML help and Markdown documents remain 100% physically identical.

3. CI/CD Integration Checks:

   • Run the operational documentation verification suite (verify_pages.py) to confirm that all cross-links, sidebars, and external tabs continue to function without errors on local development servers.