Exclusion Gates & Ignore Filters

In large enterprise codebases, documentation portals can easily become cluttered with private boilerplates and internal helpers. Flude 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. As of v2.0, path/file-based scoping is partially available (three collector-config keys, documented below) — a general namespace-based scope or a true include allowlist is not yet available; see the corrected section below.

---

🚪 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

Flude 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.

/**
 * \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)

// DOM-IGNORE-BEGIN
class PrivateHelperEngine {
    void InternalSetup();
};
// DOM-IGNORE-END

/// @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; link retargeted 2026-08-14 from the retired srs/functional page to the new requirements catalog). :::

---

🤖 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 Flude 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.

---

📁 Path/File Exclusion — Available Since v2.0 (corrected 2026-08-14)

This section previously stated that no path/file-based exclusion existed. That was wrong as of v2.0 and has been corrected. Three declared ude_doc_config.json collector keys are wired directly into the generated Doxyfile (engine/ude/collectors/doxygen.py, verified against source):

• exclude — a list of real file/directory paths (anchored to the source directory), wired to Doxygen's EXCLUDE key.
• exclude_patterns — wildcard patterns (e.g. "*/Gi/*"), passed through verbatim to Doxygen's EXCLUDE_PATTERNS key.
• file_patterns — file-extension/name patterns (e.g. "**/*.h"), wired to Doxygen's FILE_PATTERNS key. A leading **/ is stripped automatically so "match at any depth" keeps its meaning against Doxygen's own per-directory FILE_PATTERNS matching.

These are real, declared config keys — not the collector.doxyfile_template escape hatch described below — and are already used in production. Worked example, from a shipping SDK config (ude_projects/Kernel/kernel_api_cpp/ude_doc_config.json):

{
  "collector": {
    "file_patterns": ["**/*.h", "**/*.hpp"],
    "exclude_patterns": ["*/Gi/*", "*/detail/*"]
  }
}

Still genuinely missing (tracked as REQ-FUN-51 / REQ-V3-09: Path/File/Namespace Include-Exclude Scoping, traces to REQ-BUS-14, targeted V3.0 — not the banned "v2.0+" catch-all this section used to cite):

• A true include allowlist distinct from file_patterns-style narrowing.
• Namespace-name-based scoping (as opposed to file-path-based scoping — the keys above operate on paths, never on a parsed namespace or symbol name).
• An implementation independent of Doxygen — the current mechanism is entirely a Doxyfile pass-through, so it will need reimplementing once native (non-Doxygen) parsers ship.

Two mechanisms remain genuinely absent, unchanged from before this correction:

• 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 Flude ignore mechanism.
• A project can additionally reach Doxygen's own EXCLUDE/FILE_PATTERNS keys by supplying a custom collector.doxyfile_template file, since Doxyfile tiers are merged generically — this remains a valid Doxygen-level escape hatch alongside the three declared keys above, useful for Doxygen options the declared keys don't expose.

---

📊 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.