Filters

The most common filter in C++ libraries is by qualified name. include-symbols keeps only the symbols whose names match one of the listed globs. The usual entry point is the library’s top-level namespace. exclude-symbols then drops a glob inside that set. Two patterns are common: the unsafe_* family of functions (faster variants that skip validation, on the assumption the caller has already validated), and a helper namespace like jzon::extra for tracing or debug hooks the public docs do not need.

Three patterns drive that output:

The pattern delimiter is :: instead of /. A single * matches anything that does not cross a ::, so jzon::* matches jzon::parse but not jzon::extra::enable_trace. A double ** matches everything including ::, so jzon::** matches both.

Sometimes a type that lives in the library’s implementation appears in a public signature: a return type, a parameter, an inherited base. Dropping it with exclude-symbols would break cross-references and leave the reference as a bare name. The two options below keep the symbol in the corpus and hide its details from the reader.

implementation-defined drops the page for the matched symbols and renders any reference to them as /* implementation-defined */. see-below is gentler: the symbol keeps its page, but the synopsis collapses to /* see-below */ and the members are not enumerated. Use see-below when the type matters to the reader but its implementation does not. Use implementation-defined when the type’s name should not be advertised.

implementation-defined matches two patterns. 'logr::detail::**' catches the conventional internal namespace, and 'logr::*_impl' catches the _impl-suffixed forward declarations the library uses as opaque customization-point handles. Where either type appears in the signature of scoped_context or set_encoder, the rendered synopsis substitutes /* implementation-defined */. see-below matches logr::log_record: the type keeps its page, but the synopsis on that page collapses to /* see-below */, so the reader sees what the type is rather than how it is laid out.

Reach for path filters when the libraries you want to keep share a naming scheme that a symbol filter cannot separate, or when the source tree contains directories (vendored code, generated headers) that should not appear in the docs at all.

input is the list of directories MrDocs scans for sources. A miniature FFmpeg layout makes the case: every public function across libavcodec, libavformat, and friends sits at global scope under the same av_* prefix, so include-symbols: ['av_*'] would pull them all in. Only the directory tells them apart.

Only include/libavcodec is in input, so the format-library functions never enter the corpus. The default is <source-root>/., which covers the whole project.

recursive decides whether MrDocs walks into subdirectories under each input root. Set it to false when only the top-level files of a directory are public.

The exclusion side of the same axis: exclude drops a specific subdirectory inside input. Use it for code that does not belong in the output, such as a vendored copy of a third-party library or a generated-code tree that lives next to the source. The example below documents the httpd library while skipping a vendored copy of zlib that the project bundles for convenience:

exclude-patterns is the glob form of exclude and matches across the tree, so one pattern can drop every directory matching the glob no matter where it sits under input. The classic case is build-generated headers that live next to each component’s hand-written ones under a _generated/ subdirectory:

A single '**/_generated/**' pattern drops both storage/_generated/ and payments/_generated/. With the literal exclude:, you would need one entry per directory.

file-patterns narrows the file set MrDocs scans inside the input directories: only files whose names match one of the globs are read. The default already covers the common C++ header extensions, so you set it only to narrow further (for example, to skip .ipp).

The extract-* family flips MrDocs’s category-level defaults: each option toggles a class of declarations that the default would either include or omit. The two most common are below. The reference page covers the rest (static locals, anonymous and empty namespaces, friends, local classes, implicit template specializations); reach for one when you discover the default is hiding something you wanted documented.

Symbol and file patterns share the same wildcards (the file form uses / as the path delimiter; the symbol form uses ::):

Inclusion rules (include-symbols, implementation-defined, see-below) are intentionally looser than exclude-symbols: a symbol counts as included when any of the following hold.

Exclusion rules require a strict match: a symbol is excluded only when it (or its scope) is the pattern’s exact target.