Universal Documentation Engine Operational Documentation

Appearance

Exclusion Gates & Ignore Filters ​

In large enterprise codebases, documentation portals can easily become cluttered with private boilerplates and internal helpers. UDE provides a small, precise set of exclusion mechanisms to keep your public developer API documentation clean — but it is important to know exactly what is and isn't filtered automatically, since there is no general path/file/namespace-based include-exclude configuration today.

🚪 Why Filter Documentation? ​

Not all code is meant to be exposed. Internal helper classes and low-level implementation details distract external developers and increase cognitive load. By filtering out non-public APIs, you:

  • Ensure users focus only on public, supported APIs.
  • Keep compiled index sizes small for fast search and load times.
  • Prevent leaks of internal implementation details.

🛠️ Exclusion Techniques ​

UDE supports the following real, source-level filtering mechanisms:

1. Member & Class Tagging (@internal / \internal) ​

The @internal or \internal tag, placed anywhere in a docstring, causes the entire class, method, enum, or field/variable to be silently dropped from the catalog entirely — not rendered, not linked, not even counted anywhere downstream. This check is applied independently at the class, method, enum, and field/variable level.

cpp
/**
 * \internal
 * This class handles memory buffer layouts and should not be public.
 */
class BufferLayoutManager { ... };

2. Conditional / Ignored Blocks (DOM-IGNORE-BEGIN/END, \cond/\endcond, @cond/@endcond) ​

cpp
// DOM-IGNORE-BEGIN
class PrivateHelperEngine {
    void InternalSetup();
};
// DOM-IGNORE-END
cpp
/// @cond
void SecretCallbackAPI();
/// @endcond

Both forms (optionally XML-comment-wrapped) are stripped from the raw Doxygen XML text via regex, before any XML parsing happens — so any nested tags inside the block are removed wholesale, along with everything else in the block. This is a text-level deletion, not a catalog-level filter.

3. Anonymous Doxygen-Generated Enums ​

Enums that Doxygen itself generates anonymously (internally named @N) are automatically dropped from the catalog.

4. Doxygen-Synthesized "Phantom" Namespaces ​

Namespaces Doxygen synthesizes with no real source file (marked location file="[generated]") are automatically skipped.

:::note Functional Traceability: Direct support for inline annotation filtering traces to REQ-FUN-13: Ignore Tags & Range Boundaries (previously mis-linked here as REQ-FUN-30, which was later reassigned to an unrelated TOC-hierarchy requirement — corrected 2026-07-21). :::

🤖 SWIG Boilerplate Filtering — Not Automatic Today ​

Unlike the mechanisms above, SWIG plumbing filtering is not wired into any real config-driven build. The parser does have an exclude_swig_internals flag that, if enabled, drops a specific hardcoded set of names:

  • Fields: swigCPtr, swigCMemOwn
  • Methods: Dispose, getCPtr

However, this flag is not exposed through any JSON config key, and the orchestrator never passes it when constructing a parser from a doc-config. In practice, a real config-driven UDE build never filters SWIG boilerplate automatically — the flag is only reachable by code that instantiates the parser directly as a Python library. Do not expect a filter_wrappers, exclude_namespaces, or similar JSON key to exist — it doesn't.

🚫 No Path/File-Based Exclusion (planned — REQ-FUN-51) ​

There is currently no way to include or exclude entities by file path, glob, or namespace name from UDE's own configuration. This gap is now tracked as REQ-FUN-51: Path/File Glob-Based Include-Exclude Filtering (traces to REQ-BUS-14), targeted for v2.0+ — until it ships, do not assume any of the mechanisms below exist:

  • A .agyignore file exists in the engine repo, but it is a standard .gitignore-style file — it is never read by any engine code. It is not a UDE ignore mechanism.
  • There is no FILE_PATTERNS/EXCLUDE-style JSON config key wired from a doc-config into the Doxygen invocation.
  • A project can still reach Doxygen's own EXCLUDE/FILE_PATTERNS keys by supplying a custom collector.doxyfile_template file, since Doxyfile tiers are merged generically — but this is a Doxygen-level escape hatch, not a UDE config-level knob.

📊 Coverage Gate vs. Exclusion — These Are Different Things ​

The documentation coverage gate (ude audit, or the automatic post-compile audit table) is not a file/entity exclusion mechanism. It never removes anything from output. It only excludes specific names from its own coverage-percentage calculation: private _foo/dunder __foo__ names, logger, and a small hardcoded set of known Doxygen/Python-parser false-positive artifacts.

  • Entities removed by @internal, conditional blocks, anonymous enums, or phantom namespaces never reach the catalog at all — they don't appear in output or in coverage statistics, because they were never counted in the first place.
  • Entities the coverage gate excludes by name (private/dunder members, logger, known parser artifacts) still appear in rendered output — they're just excluded from the coverage percentage, satisfying REQ-BUS-08: Documentation Coverage & Quality Gate Separation.

Copyright © 2026