-
REQ-FUN-06 (AI Translation Lifecycle & States):
- Target Release: Future Phase (v2.0+)
- Translation Lifecycle Statuses: Each translation entry in the cache database must support a state metadata flag:
draft (default for AI-generated translations) or verified (marked after Translation Manager manual review/override or XLIFF import).
- Translation Pipeline Triggers: The translation generator module must execute strictly upon commits or merges into the primary production branch (
master). Standard feature-branch builds are restricted from making live translation API calls and must execute in secure Read-Only mode.
- Traces to:
REQ-BUS-06
-
REQ-FUN-18 (Asynchronous Non-Blocking Translation CLI):
- Target Release: Future Phase (v2.0+)
- Decoupled Non-Blocking Workflow: The translation review cycle must be decoupled from code integration. Standard development builds must render
draft translations (optionally displaying a configurable "AI-translated draft" warning banner) or fall back to the source English language, ensuring developer velocity is not impacted by manual localization checks.
- Access Control Modes: The CLI must support a
--read-only-cache flag (active by default for general CI/CD builds) to parse and render using existing translation files without making writes, and a --write-cache flag (restricted to authorized Translation Manager sessions in CI/CD) to safely commit updates and state promotion (from draft to verified) to the translation database.
- Traces to:
REQ-BUS-06
-
REQ-FUN-08 (Server-Side Push-Gate Enforcement Modes):
- Target Release: Future Phase (v2.0+)
- Server-Side Modes: Under
--push-gate-mode, the gate enforces policies (reject, allow, auto-document, verify-document).
- Traces to:
REQ-BUS-08
-
REQ-FUN-15 (Quality Gate Scope & Completeness Criteria):
- Target Release: Future Phase (v2.0+)
- Quality Gate Scope: The Quality Gate calculates documentation coverage over all public (
public) and protected (protected) API entities (including classes, interfaces, methods, functions, properties, fields, enums, structs, constants, constructors, etc.) within the scope of code ingestion.
- Documentation Completeness Criteria: An entity is classified as fully "documented" if and only if:
- It has a non-empty, meaningful prose description in its docstring.
- If the entity is a method or function containing parameters or a return value, every single parameter and the return value must also have non-empty, associated descriptions in the docstring schema.
- Traces to:
REQ-BUS-08
-
REQ-FUN-16 (Quality Gate Automatic Exclusions):
- Target Release: Future Phase (v2.0+)
- Automatic Exclusions: The following elements are automatically excluded from the Quality Gate denominator:
- Overridden methods that are explicitly inherited without structural changes from base classes or external system libraries (e.g.,
Equals, GetHashCode, ToString in Java/C#, or __str__, __repr__ in Python).
- Trivial property getters and setters (e.g., automatic properties
get; set; in C#) containing no custom user logic.
- Traces to:
REQ-BUS-05, REQ-BUS-08
-
REQ-FUN-17 (Offline Local Gate Fallbacks):
- Target Release: Future Phase (v2.0+)
- Offline Local Execution: When executed outside a CI/CD environment (detected via environment variables or explicitly passed CLI flags), UDE must enforce an offline-by-default execution policy, utilizing local cache databases or mock placeholders instead of billing live LLM APIs.
- Traces to:
REQ-BUS-05
-
REQ-FUN-12 (Standalone Coverage Reporting Command):
- Target Release: Future Phase (v2.0+)
- Independent CLI Execution: The UDE CLI must support a dedicated, standalone subcommand (e.g.,
ude coverage) to audit documentation coverage and output reports. This command must be fully executable independently of the main documentation compilation and rendering workflow.
- Reporting Formats: The coverage command must generate structural reports detailing:
- Total audited entities, total documented entities, and the aggregate coverage percentage.
- A comprehensive list of specific undocumented or partially documented entities (with file names and line numbers).
- Outputs in multiple formats, including human-readable CLI terminal prints, detailed Markdown summaries, and structured JSON for integration with external dashboards.
- Traces to:
REQ-BUS-08
-
REQ-FUN-13 (Ignore Tags & Range Boundaries):
- Structural Exclusions: The parser, quality gate, and coverage modules must completely ignore any code blocks or entities demarcated by the following tags:
- Block Range Exclusions: All code and entities situated between
DOM-IGNORE-BEGIN and DOM-IGNORE-END comments.
- Conditional Block Exclusions: All code and entities situated between
\cond (or @cond) and \endcond (or @endcond) directives.
- Internal Tag Exclusions: Any entity containing or marked with the
\internal (or @internal) tag.
- Traces to:
REQ-BUS-05, REQ-BUS-08
-
REQ-FUN-09 (Context-Rich Source Ingestion & Decoupled Tooling): The ude-enrich module/script must extract both the declaration (signature) and the definition (implementation body/block) for any undocumented code entity. When sending a prompt to the LLM for English docstring generation, this tool must construct a composite payload containing both the declaration and the full implementation body as context, ensuring that the generated docstrings accurately reflect the internal logic, thrown exceptions, and side-effects of the code. The tool must write back only the resulting docstrings to the source code or output documentation without altering any functional logic.
- Target Release: Future Phase (v2.0+)
- Traces to:
REQ-BUS-05
-
REQ-FUN-10 (XLIFF Export and Import CLI Commands): The UDE CLI must support standard subcommands for exporting and importing localization files in XML Localisation Interchange File Format (XLIFF, .xlf format, version 1.2 or 2.0) to enable integration with professional translators:
- Target Release: Future Phase (v2.0+)
- Export Command (
ude translation export <lang> --output <file.xlf>): Extract all source English docstrings and prose blocks alongside their corresponding AI-proposed translation segments with a status of draft, formatting them into a standard XLIFF translation unit (<trans-unit>) containing <source> and <target> nodes.
- Import Command (
ude translation import <file.xlf>): Ingest a translated .xlf file back into the local translation cache, updating translation strings and automatically promoting their lifecycle status from draft to verified.
- Traces to:
REQ-BUS-06
-
REQ-FUN-07 (Non-Interactive CLI Automation): The CLI engine must support execution in completely non-interactive mode with standard exit codes, configurable via command-line arguments and environment variables, for hands-free automation in CI/CD pipelines.
-
REQ-FUN-11 (Transparent Compression of JSON Artifacts): The engine must store and manage all persistent JSON artifacts—specifically the Intermediate Representation (IR) files and the Translation Cache database—in a compressed format using the standard Gzip algorithm (with file extension .json.gz). The CLI orchestrator and modular subcommands must transparently decompress these files into memory upon startup or ingestion, and compress them back to disk upon execution completion or export, ensuring zero uncompressed JSON pollution in repository storage.
- Baseline (MVP v1.0): Intermediate Representation compression.
- Future Phase (v2.0+): Translation Cache compression.
- Traces to:
REQ-BUS-03
-
REQ-FUN-23 (Environment & Dependency Verification):
- Version 1 (Baseline / MVP): Before initiating execution of any collector or parsing task, the orchestrator and the collector must perform strict environment pre-flight checks:
- Verify that Python is installed, executable, and accessible on the system PATH (since the orchestrator and parsing engine run as Python scripts).
- Verify the availability and execution permission of the Doxygen binary (as specified in
ude_global_config.json or fallback system paths) if the project requires Doxygen preprocessing.
- Verify the physical presence of all required target configurations (e.g.,
ude_doc_config.json and Doxyfile for Doxygen-based projects).
- Verify the existence, accessibility, and non-emptiness of all target source directories (
src_dir).
- Verify the presence of all necessary raw source code files (e.g.,
.h files for C++, .cs files for C#, etc.) within those source directories required to compile or parse the specific project.
If any checks fail, execution must be halted cleanly before subprocess spawn, throwing an environment-specific exception, writing diagnostic recommendations to stderr, and exiting with code 5.
- Traces to:
REQ-BUS-09
-
REQ-FUN-24 (Pipeline Fault Tolerance & Recovery):
- Version 1 (Baseline / MVP): The system must enforce high-reliability operational boundaries:
- Multi-Project Execution Policy: When orchestrated via
generate_all.bat, the orchestrator must support a configurable error policy (via ude_global_config.json): fail-fast (abort the entire pipeline run at the first project error) or continue-on-error (log the target failure, skip the failed project, continue compilation of remaining projects, and print a consolidated error list at the end).
- Malformed XML Protection: If individual generated XML files are malformed or unreadable, the parser must log specific warnings and proceed to extract structural entities from other valid compounds, avoiding total pipeline crashes.
- Crash Cleanup Guarantee: If an unhandled exception or pipeline failure occurs during execution, the system must trigger automated cleanup via
finally blocks to delete any generated temporary folders or XML files, preventing workspace contamination.
- Traces to:
REQ-BUS-03, REQ-BUS-09
-
REQ-FUN-25 (Unified Logging & Auditing):
- Version 1 (Baseline / MVP): The engine must implement a centralized, time-stamped, and thread-safe file-logging system writing to a configured log file (e.g.
ude_system.log). The logging module must:
- Document the starting parameters, timestamped progression, and duration of every lifecycle phase (Collect, Parse, Validation, Render, Cleanup).
- Intercept and capture Doxygen subprocess stderr logs, categorizing compiler warnings and errors into the unified UDE log stream.
- Log parse statistics (count of extracted namespaces, classes, methods, parameters, and entities) and rendering outputs (pages written).
- Support configurable logging verbosity levels (
DEBUG, INFO, WARNING, ERROR).
- Write detailed stack traces of any occurring exceptions to the log file, while printing only high-level, clean, and developer-friendly diagnostic messages to the console stderr.
- Traces to:
REQ-BUS-03, REQ-BUS-09
-
REQ-FUN-26 (Incremental Parsing Cache):
- Version 1 (Baseline / MVP): To prevent redundant parsing, the engine must implement incremental parsing based on file modification timestamps or content hashes (e.g. SHA-256) of input Doxygen XML files. If an XML compound (representing a class, namespace, structure, etc.) has not changed since the previous run, its corresponding entities must be loaded directly from
.build_cache.json.gz, bypassing raw XML parsing to reduce execution time.
- Traces to:
REQ-BUS-03, REQ-BUS-09
-
REQ-FUN-27 (Incremental Rendering Cache):
- Version 1 (Baseline / MVP): To optimize documentation rendering (preventing redundant disk writes, reducing SSD wear, and keeping Git commits of local outputs clean), the renderer must support incremental rendering. It must compare the signature hash (or content hash of the IR entity) and template hash against the previously rendered files. If neither has changed, the renderer must skip rewriting the target output file.
- Traces to:
REQ-BUS-03, REQ-BUS-09
-
REQ-FUN-28 (Target Folder Isolation for Metadata and Cache):
- Version 1 (Baseline / MVP): All pipeline-internal files—specifically the Intermediate Representation (
intermediate_representation.json.gz) and build/parsing caches (.build_cache.json.gz)—must be strictly stored within a dedicated target subdirectory under the ude/ tree, named according to the format <sdk>_<lang> (e.g. ude/Bimnv/bimnv_cpp/, ude/Bimnv/bimnv_cs/). This <sdk>_<lang> folder is a descendant of the ude/ root directory, is kept under git version control, and contains the target-specific batch script, ude_doc_config.json, and Doxyfile. Intermediate and cache files must never be written to output_dir (which contains final user-facing files only) to ensure a clean separation between development metadata and production assets.
- Traces to:
REQ-BUS-03
-
REQ-FUN-29 (No Hardcoded Paths & Relative Path Resolution):
- Version 1 (Baseline / MVP): All directory and file paths used by the UDE engine must be defined exclusively in the configuration files (
ude_global_config.json, ude_doc_config.json, product.json, etc.). Under no circumstances shall physical paths be hardcoded directly into the Python source code. Furthermore, all paths declared in the configurations must be relative (relative to the directory containing the config file). At runtime, the UDE orchestrator must automatically resolve and translate these relative paths into absolute paths, ensuring seamless portability between local developer environments and CI/CD servers.
- Traces to:
REQ-BUS-09
-
REQ-FUN-30 (TOC Logical Hierarchy & Physical Flat-Mapping):
- Version 1 (Baseline / MVP): The rendering engine must support compiling structured API Table of Contents (TOC) trees for all base languages (C++, C#, Java, Python).
- Logical Hierarchy Rules:
- C++: Namespace -> Nested Namespace -> Classes/Structures/Enums/Global Functions -> Nested Classes -> Methods/Fields.
- C#: Namespaces (nested by dot separation) -> Classes/Interfaces/Enums -> Nested Classes -> Methods/Properties/Fields.
- Java: Packages (nested by dot separation) -> Classes/Interfaces/Enums -> Nested Classes -> Methods/Fields.
- Python: Packages -> Modules -> Classes/Functions -> Nested Classes -> Methods/Properties.
- Physical Flat-Mapping Rules (Disk naming without deep folder nesting):
- C++: Hierarchy levels separated by double underscore
__ (e.g., FacetModeler::Body::faceCount -> FacetModeler__Body__faceCount.html). Overloaded method signatures separated by @ (e.g., apply(double) -> ...__apply@double.html). Safe string replacements for special characters (e.g., * -> _ptr, & -> _ref, < -> _lt_, > -> _gt_).
- C#: Dot package/namespace levels and nested classes separated by
__ (e.g., Oda__Cloud__Connection.html). Overloads separated by @ with safety replacements.
- Java: Package levels separated by a single underscore
_, nested class members separated by __ (e.g., org_graphics_Oda__Class.html). Overloads separated by @.
- Python: Package/module dot levels and class levels separated by a single underscore
_, member methods/properties separated by __ (e.g., ude_parsers_doxygen_DoxygenXmlParser__parse_file@str.html).
- Traces to:
REQ-BUS-10
-
REQ-FUN-31 (Multi-Format TOC Compilation & Sidebar Interactive Features):
- Hugo Markdown TOC Integration: The renderer must compile logical TOC paths into YAML/TOML front-matter metadata headers inside individual Markdown output files (utilizing standard key schemas:
title, weight, parent) enabling native Hugo menu hierarchy assembly.
- HTML Offline Sidebar (No CORS Restriction): Standalone HTML output must feature an offline-ready, dynamic sidebar loaded strictly via file protocols (
file:///). To prevent browser CORS security blocks:
- The hierarchical TOC database must be compiled as a global JSON object (
window.UDE_NAV_DATA) inside a dedicated JavaScript file nav_data.js and loaded dynamically via a <script> tag.
- The sidebar must render an interactive tree. Clicking on folder nodes collapses or expands them without triggering page reloads.
- Interactive Sidebar Control & Search:
- Resizable Panel Splitting: Include a draggable vertical splitter handler (
.OdaDocSplitter) that allows the user to resize the sidebar width. The user's custom width must be persistently stored in the browser's localStorage under the key ude_sidebar_width and automatically re-applied on subsequent page loads.
- Real-Time Search Filter: Provide a fast, client-side text input filter (
#sidebarSearch / #odaTocSearchInput) that performs real-time matching against TOC entity labels, auto-expanding parent scopes to reveal search results and hiding unmatched nodes.
- Active Node Focus & Auto-Scrolling (HTML & Hugo): On page load, the sidebar must automatically focus on the navigation node representing the currently active page. It must automatically expand all parent folders/namespaces of the active node to make it visible. Furthermore, the sidebar container must automatically scroll so that the active node is positioned as high as possible within the sidebar's visible viewport (at the top of the scrolling container) to ensure immediate context visibility. This behavior must be implemented identically for both the standalone offline HTML Help portal and the Hugo static site.
- Traces to:
REQ-BUS-10, REQ-BUS-02
-
REQ-FUN-32 (Standardized Entity-Type Page Layouts):
- Version 1 (Baseline / MVP): The rendering templates must generate standardized layout structures for each public API entity page (classes, structures, and interfaces) across all supported languages.
- Page Template Anatomy:
- Visual Header: Display the entity's fully qualified name alongside a highly visible, color-coded typographic badge designating the entity type (e.g.,
[class], [method], [module]).
- Prose Description Block (
.OdaDocBrief): Section displaying the CommonMark normalized brief and detailed documentation prose.
- Metadata Panel (
.OdaDocContainerTable): A clean tabular container detailing vital structural context (e.g., source file origin, enclosing parent module/namespace, access scope, and inheritance lines).
- Code Prototype Block (
.OdaDocCodeProto): Code declaration blocks styled with specific CSS layouts, marked with the exact language-tag required for Highlight.js code highlighting.
- Expandable Member Tables: Collate nested children (e.g., methods inside a class, fields inside a struct) into distinct, collapsible sections containing navigation tables. Each row must feature a high-fidelity visual indicator icon (such as
indicator-method-16.png) denoting the member's specific subtype and accessibility.
- Language-Specific Custom Templates: Each target language must utilize its own distinct HTML template (or unique customization parameters) specifying how class/module declarations, methods, properties, fields, and constructors are visually presented (e.g., correct scope delimiters like
:: vs ., base class inheritance syntax, and parameter lists) to ensure 100% look-and-feel alignment with native coding standards.
- Aesthetic and Visual Matching:
- Style Compilation: The HTML compiler must copy the reference stylesheet
main.css and all visual indicator images from the directory specified globally in ude_global_config.json under "stylesheet_dir" to the output generation directory.
- Styles Integration: Each generated HTML page must reference the local
main.css inside its <head> section via <link rel="stylesheet" href="main.css">.
- Visual Look & Feel Exactness: The overall layout appearance, color palette (employing ODA primary
#ff3100 and hover #cc2600), typography, responsive breakpoints, spacing, and panel sizing rules must be visually indistinguishable from the reference pages.
- Traces to:
REQ-BUS-10
-
REQ-FUN-33 (Multi-Entity Dynamic File Prefixing & Page Coverage):
- Version 1 (Baseline / MVP): Standalone pages are generated for extracted high-level object-oriented entities (classes, structures, and interfaces). The physical filename of each generated page on disk, resolved by the
resolve_filename() method in both HTML and Hugo Markdown renderers, must be dynamically prepended with the exact, lowercase entity type (class_, struct_, interface_) followed by an underscore (e.g. class_MyClass.html, struct_MyStruct.html, interface_MyInterface.html). Other high-level entities (such as namespaces, packages, modules, enums, global functions, and variables) are represented hierarchically or inline within the generated documentation rather than having separate standalone pages in this baseline version.
- Unified Signature: This rule must apply universally across all supported languages (C++, C#, Java, Python) for all generated class, structure, and interface files.
- Excluded Entities: Members and other non-class entities do not generate separate standalone pages.
- Traces to:
REQ-BUS-02, REQ-BUS-10
-
REQ-FUN-34 (Integrated Document Catalog Link & Reference):
- Version 1 (Baseline / MVP): The generated technical publications must support injecting custom catalog or central index links. If configured, these links are rendered consistently inside the global navigation sidebar or footers of all compiled documentation types, allowing developers to jump to user-defined manuals and guides.
- Unified Access: This catalog reference link must be rendered consistently inside the global navigation sidebar or footers of all compiled documentation types.
- Traces to:
REQ-BUS-11
-
REQ-FUN-35 (No Empty Sidebar Sections & Auto-Linking):
- Version 1 (Baseline / MVP): The documentation system's sidebar generation must enforce that every sidebar category, group, or node corresponds to a real, navigable page (preventing empty collapsible headers that do not open any page). If a sidebar section is defined, it must:
- Direct the user to an explicit index/category page.
- Or link to its first-level child document (the first descendant page under that section).
- Or render a dynamically generated index page that lists all first-level children of that category.
This rule applies strictly to UDE's automatic API Reference sidebar/TOC compiler to ensure that every auto-generated structural category or group resolves to a valid index page or first-level child.
- Target-Specific Sidebar and Folder Layouts:
- Hugo Generation (Flatter Structure and Namespace Tables): In the Hugo site build, intermediate virtual grouping directories (such as "Classes", "Structures", or "Interfaces") are completely omitted from both the physical folder structure and the sidebar menu. Instead, class-level and namespace-level documents are flat-mapped directly under their parent namespace, producing a direct, cleaner menu layout. To ensure seamless navigation, the compiler MUST dynamically generate a dedicated Markdown index page for each Namespace. This namespace index page must contain a structured table listing all child entities (classes, structures, interfaces) in that namespace. Each table row must present the entity's name (formatted as a clickable link pointing to its respective documentation page) alongside its brief description/prose (
.OdaDocBrief), providing a clear directory landing view.
- Standalone HTML Generation (Hierarchical Index Pages): In the standalone offline HTML Help generator, if the sidebar renders collapsible virtual category folders (such as "Classes", "Structures", or "Interfaces") based on the language configuration rules, the compiler MUST dynamically generate a dedicated HTML index page for each group folder. This page must visually list all compiled children within that category (e.g., providing quick links to each class) and serve as the navigable destination for that category folder, eliminating any pageless sidebar categories in offline view.
- Language-Specific JSON Mapping: The generated sidebar hierarchy must dynamically conform to the rules and virtual groupings specified in the respective language-specific JSON configurations (
toc_cpp.json, toc_cs.json, toc_java.json, toc_py.json). However, to avoid empty/dead folders, a virtual category node must only be created in the sidebar if there is at least one active, compiled entity of that type under the parent namespace/package scope. Any virtual category with zero entities in a compiled target must be pruned on-the-fly.
- Traces to:
REQ-BUS-10
-
REQ-FUN-36 (Standardized Welcome Pages):
- Version 1 (Baseline / MVP): Both
HtmlRenderer (rendering standalone offline HTML) and HugoMarkdownRenderer (rendering Markdown files for Hugo) must output an identical landing page title and description:
- Page Title:
"API Reference Welcome"
- Page Body / Description: "Welcome to the API Reference documentation portal. Please browse the sidebar to explore code entities."
This ensures that when a user first enters the API Reference section of any generated portal, they are greeted by a consistent, standardized message across all output formats.
- Traces to:
REQ-BUS-10
-
REQ-FUN-37 (Standardized Namespace Landing Page Briefs):
- Version 1 (Baseline / MVP): Both HTML and Markdown compilation pipelines must generate standard, uniform introductory headers at the top of namespace index/landing pages (e.g.
_index.md for Hugo or namespace_<id>.html for HTML). The brief description must consistently read: "List of classes in the <NamespaceID> namespace."
The renderer must dynamically adapt the rendering of \<NamespaceID\> to match target language and format patterns (e.g., as code blocks \{namespace.name\} in Markdown, or formatting delimiters :: to . for non-C++ languages).
- Traces to:
REQ-BUS-10
-
REQ-FUN-38 (Header Branding & Dual-Portal Cross-Linking):
- Version 1 (Baseline / MVP): The VitePress-based operational documentation portal header configuration must strictly conform to the following branding and navigation design system:
- Header Title & Logo: The header must display the logo (loaded from
/logo.png) alongside the text title "Universal Documentation Engine Operational Documentation".
- Dual-Portal Cross-Linking: The navigation bar must include exactly two main links to bridge static user-facing docs and live-generated API Reference portals:
"User Docs" link pointing to /docs/chapter1-quick-start with target set to _blank to open in a new tab."API Reference" link pointing to https://ude-api-ref.pages.dev/ with target set to _blank to open in a new tab.
- Visual Indicators: Both links must be styled with external link icons and must open cleanly in a new browser tab with appropriate
rel="noopener noreferrer" attributes to ensure security and performance.
- Traces to:
REQ-BUS-10
-
REQ-FUN-39 (Multi-URL Active Sidebar Highlighting):
- Version 1 (Baseline / MVP): The sidebar layout templates inside the Hugo-based static website renderer must use environment-agnostic tests against the page's relative URL (
.RelPermalink) to determine whether the main welcome navigation card is highlighted as active.
To guarantee the active state persists regardless of whether the site is hosted on a local development server or compiled inside production root/subdirectories, the active state check for the "API Reference Welcome" card must evaluate as true if and only if .RelPermalink is exactly equivalent to either /, /api/, or /ude-user-docs/api/.
- Traces to:
REQ-BUS-10
-
REQ-FUN-40 (SWIG Pointer Type Mapping & Cleanup):
- Version 1 (Baseline / MVP): During parsing of SWIG-generated C# and Java wrapper code, the parsing module must automatically detect low-level, generic SWIG-specific pointer types (specifically matching the pattern
SWIGTYPE_p_<type> such as SWIGTYPE_p_double, SWIGTYPE_p_void, or platform-specific pointer handles like HandleRef) and map them to their clean, natural language-native equivalents:
- For C#: Convert
SWIGTYPE_p_double to double[] or ref double (depending on API context), and SWIGTYPE_p_void to System.IntPtr.
- For Java: Convert
SWIGTYPE_p_double to double[] and SWIGTYPE_p_void to java.nio.ByteBuffer or long.
This cleanup must be performed inside the Intermediate Representation (IR) compiler stage, ensuring that final rendered developer documentation displays clean, natural types instead of raw SWIG plumbing types.
- Traces to:
REQ-BUS-01, REQ-BUS-10
-
REQ-FUN-41 (C++ Template Parameter Extraction & Rendering):
- Version 1 (Baseline / MVP): The C++ parsing and normalization modules must support extracting template parameter documentation tags (specifically
\tparam or @tparam directives) from comment blocks.
- Extraction: Map template parameter names and their accompanying text descriptions into structured metadata within the Intermediate Representation (IR) entity schema.
- Layout Rendering: The HTML and Hugo-Markdown rendering engines must display these template parameters inside a dedicated, highly visible metadata table or block (labeled "Template Parameters") situated directly below the class/method header and above the standard parameter list.
- Traces to:
REQ-BUS-01, REQ-BUS-10
-
REQ-FUN-42 (Language-Specific Signature Formatting Strategy):
- Version 1 (Baseline / MVP): The rendering system must employ an extensible Strategy Pattern to handle formatting of code declarations, namespace structures, scopes, and names tailored to each target programming language (C++, C#, Java, Python). This is mediated via a polymorphic interface
BaseSignatureFormatter and a dynamic selection factory get_signature_formatter(language). The system must normalize namespace boundaries, prefix syntax, class structure headers, and dynamically assemble fallback method signatures if physical documentation elements are missing.
- Traces to:
REQ-BUS-02, REQ-BUS-10
-
REQ-FUN-43 (Robust Layout Template Loading & Inline Fallback):
- Version 1 (Baseline / MVP): The static HTML rendering engine must implement a dual-stage fallback layout loading mechanism to ensure high fault tolerance and complete resilience against compilation crashes:
- Primary Loader: The engine attempts to load a language-specific template (e.g.,
templates/\<lang\>/class_layout.html) using a physical filesystem loader.
- Secondary Fallback: If the language-specific directory or template does not exist, the renderer must transparently fall back to the root default template
templates/class_layout.html.
- Fail-Safe Inline Fallback: If no physical template directory or files are found on disk, the system must initialize a default in-memory layout using a predefined, high-fidelity inline template string to guarantee error-free local and CI/CD verification regardless of host filesystem layout states.
- Traces to:
REQ-BUS-02, REQ-BUS-09
-
REQ-FUN-44 (Backward-Compatible Multi-Language Parser Facade):
- Version 1 (Baseline / MVP): To decouple language-specific parsing details from orchestration and testing components, the ingestion pipeline must employ a unified Parser Facade (
DoxygenXmlParser). This routing class must:
- Inherit from a universal base parser (
BaseDoxygenParser), preserving Liskov Substitution Principle (LSP).
- Dynamically instantiate and delegate work to concrete subclasses (such as
CppDoxygenParser, CsharpDoxygenParser, JavaDoxygenParser, or PythonDoxygenParser) based on an explicit language configuration.
- Support dynamic auto-detection of target programming languages using path analysis on input XML/source directories if no explicit language argument is provided.
- Maintain backward compatibility by exposing public entry points under the standard
ude.parsers.doxygen module namespace, shielding external orchestrators from internal class refactoring.
- Traces to:
REQ-BUS-01, REQ-BUS-09
-
REQ-FUN-50 (Dedicated Renderer-Specific TOC JSON Configs & Custom Pages):
- Version 1 (Baseline / MVP): The documentation engine must support defining, tracking, and rendering the sidebar structure using dedicated JSON configuration files for each of the 16 concrete renderer subclass implementations. The files must be named strictly in the format
toc_<RendererClassName>.json (e.g., toc_CppHtmlRenderer.json, toc_CppHugoRenderer.json, etc.).
- TOC Hierarchy Rules (Option A): The TOC JSON must define a single top-level array (
"sidebar") containing all root navigation items in their precise order of appearance in the sidebar. This array must support the following node types:
api_reference: Represents the root node of the Doxygen-compiled API reference tree (compiled from source code/XML metadata). The compiled API Reference must be a single tree with a single root node.static: A page compiled from an external HTML or Markdown file. In the TOC JSON, the node declares a "source_file" filename (e.g. "welcome.html"). At compile time, the engine searches for this filename within the directories listed in the "static_source_path" array defined inside the local target configuration (ude_doc_config.json). For HTML source files, only the content inside the <body> tag is extracted; for Markdown files, all content except front-matter/SSG headers is used.inline: A page where the text content is embedded directly inside the JSON configuration (written in the target output format of the renderer, but without page headers or other layout elements) under a "content" string key.redirect: A navigation node that redirects the user to a target internal relative URL or external website URL upon access.
Any static, inline, or redirect nodes declared at the root level of the "sidebar" array are treated as siblings (neighbors) to the api_reference root node, and they can nest descendant nodes under their own sub-hierarchies.
- Jinja2 Template Variable Interpolation: Both
static and inline page contents must support variable substitution using standard Jinja2 template placeholders (e.g., {{ variable_name }}). These variables must be interpolated at compile time using the unified configuration context merged from the global config (ude_global_config.json), SDK/product metadata (ude_sdk_config.json), and target-specific config (ude_doc_config.json).
- Traces to:
REQ-BUS-10