The Configuration File

MrDocs uses a configuration file to control how the documentation is generated. The file is used to specify options such as the generator to use, additional compilation options, and filters.

Here’s an example of a configuration file:

source-root: ../include
multipage: false
generator: adoc

The Usage page provides a detailed explanation of what to combine options from the configuration file and the command line.

The Reference section provides a detailed explanation of the options available.

More information about the generators can be found in the Generators page.

YAML Schema

To get linting and autocompletion in the config file, a schema for the config can be specified. The schema for mrdocs.yml is provided here.

The schema for mrdocs.yml is available from https://www.schemastore.org/json/, which is automatically detected and used by most editors.

To manually set the schema in an editor, the following can be used:

  • In JetBrains IDEs, # $schema: <url> can be used to bind a schema to a file.

  • In editors with plugins based on the YAML language server, # yaml-language-server: $schema=<url> can be used.

The following shows an example of a file specifying an inline-schema that’s compatible with JetBrains IDEs and editors using the YAML language server.

# $schema: https://mrdocs.com/docs/mrdocs/develop/_attachments/mrdocs.schema.json
# yaml-language-server: $schema=https://mrdocs.com/docs/mrdocs/develop/_attachments/mrdocs.schema.json

source-root: ../include
multipage: false
generator: adoc

Build Options

A number of options can be used to specify with which compile options MrDocs should be run.

source-root: ..
compilation-database: ../CMakeLists.txt
cmake: '-D MRDOCS_BUILD=ON'
defines: 'MRDOCS_BUILD'

The compile options primarily come from the compilation-database file. When this file is generated from a CMakeLists.txt script, the cmake option can be used to specify additional options to pass to CMake.

Additionally, the defines option can be used to specify preprocessor definitions that should be used when generating the documentation. These definitions are included in all targets of the compilation database.

Filters

Not all symbols in a project may be relevant to the documentation. MrDocs provides a way to filter out symbols based on their location and names.

File Filters

Symbols can also be filtered based on the files where they are declared. This can be useful for excluding files that exclusively contain implementation details or test code.

The input option is a list of directories to include and a list of file patterns to include. Only symbols in files from these directories will be extracted.

input:
  - ../include

The default value for input is "<source-root>/.", so only symbols defined in your project source directory will be extracted.

The file-patterns options allows you to specify a list of glob file patterns to include. Only symbols in files whose filename match these patterns will be extracted.

file-patterns:
  - '*.hpp'
  - '*.h'

The default value for file-patterns include a variety of common C++ header file extensions.

The exclude option is a list of subdirectories in input we want to exclude. Meanwhile, exclude-patterns can use glob patterns to exclude files from the extraction process.

input:
  - ../include
exclude:
  - ../include/detail
exclude-patterns:
  - ../include/*/detail/**
  - ../include/*/impl/**

The glob patterns support the following wildcards:

  • * matches all characters except delimiters /

  • ** matches all characters

  • ? matches any single character.

  • [<chars>] matches one character in the bracket.

  • [<char>-<char>] matches one character in the bracket range.

  • [^<chars>] or [!<chars>] matches one character not in the bracket.

  • {<glob>,…​} matches one of the globs in the list.

  • \ escapes the next character so it is treated as a literal.

Symbol Filters

Symbols can also be filtered based on their qualified names. You can use glob patterns to specify which symbols to include or exclude.

include-symbols:
  - 'my_library::public_namespace::*'

By default, all symbols are included by include-symbols. The syntax for symbol glob patterns is the same as for file patterns, with the exception that the delimiter :: is used instead of /. So you can match all symbols in a namespace and its subnamespaces with my_library::public_namespace::**.

The option exclude-symbols can be used to exclude symbols from the extraction process.

include-symbols:
  - 'my_library::**'
exclude-symbols:
  - 'my_library::private_namespace::**'
// excluded by `include-symbols`
void f0();

// included because it matches the prefix of 'my_library::**' in `include-symbols`
namespace my_library
{
    // included because it matches the pattern 'my_library::**' in `include-symbols`
    void f1();

    namespace private_namespace
    {
        // excluded by the pattern 'my_library::private_namespace::**' in `exclude-symbols`
        void f2();
    }
}

Private Symbols

The implementation-defined and see-below options can be used to designate symbols as implementation details or "see below" in the documentation.

include-symbols:
  - 'my_library::**'
implementation-defined:
  - 'my_library::detail::**'
see-below:
  - 'my_library::see_below::**'
namespace my_library
{
    namespace detail
    {
        // There's no documentation page for A
        // Any reference to `A` is rendered as `/* implementation detail */`
        class A {};
    }

    namespace see_below
    {
        // The documentation page for B is marked as "see below" and its members are not extracted.
        class B {
            // There's no documentation page for iterator
            class iterator;
        };
    }

    // This function is documented, but the return type is rendered as `/* implementation detail */`
    detail::A
    foo();
}

Whitelisting Rules

The rules for whitelisting symbols (include-symbols, implementation-defined, and see-below) are less strict than the rules for blacklisting symbols (exclude-symbols). A symbol is considered whitelisted if it matches any of the following conditions:

  1. The symbol strictly matches one of the patterns.

    • For instance, the patterns std::vector and std::* both match std::vector strictly.

  2. The symbol is a parent namespace of an included symbol.

    • For instance, the pattern std::filesystem::* also includes std and std::filesystem.

  3. The parent symbol is also included.

    • For instance, the pattern std::* also matches std::vector::iterator because std::vector::iterator is a member of std::vector, which is matches the pattern.

  4. The symbol is a child of a literal pattern representing a namespace.

    • For instance, the literal pattern std matches std::filesystem::path::iterator because std is a literal pattern matching a namespace. In other words, these literal patterns represent the namespace and its subnamespaces as if the pattern were std::**.

For exclusion rules, the symbol must strictly match the pattern to be excluded. If a scope is escaped by a pattern, all symbols in that scope are also excluded.

Reference

The following options can be defined both in the configuration file and on the command line, where the command line options always take precedence.

Whenever applicable, the command line options attempt to mirror (i) non-abbreviated (ii) kebab-case variants of the equivalent commands in Doxygen. For instance, the Doxygen EXTRACT_ANON_NSPACES option is mirrored by the extract-anonymous-namespaces command line option.

Command Line Options

Options that can only be provided via the command line

The following options can be used to control the general behavior of MrDocs and can only be provided via the command line. These include options to specify inputs and the configuration file, which cannot be set on the configuration file itself.

Name Description Default
cmd-line-inputs
(list of paths)
(Command line only) 		Configuration or compilation database files []
config
(file path)
(Required, Command line only) 		MrDocs configuration file "<cwd>/mrdocs.yml"

cmd-line-inputs

Configuration or compilation database files

The inputs are configuration files or compilation database files that used to generate the documentation. When the input ends with mrdocs.yml, it is interpreted as a configuration file, the file is read and the options are used to generate the documentation as if it was provided to the config option. When the input ends with compilation_database.json or CMakeLists.txt, it is interpreted as a compilation database file, the file is read and the compiler flags are used to generate the documentation as if it was provided to the compilation-database option.

  • Type: list of paths
  • Command line only
  • Default value: []
  • This command is a command line sink. Any command line argument that is not recognized by the parser will be passed to this command.

config

MrDocs configuration file

The configuration file is a YAML file that contains the options used to generate the documentation. The configuration file is read and the options are used to generate the documentation. The configuration file can be used to specify the source code, the output directory, the compilation database, the generator, and the filters.

  • Type: file path
  • Required
  • Command line only
  • Default value: "<cwd>/mrdocs.yml"

Paths

Paths to the source code and output directories

Name Description Default
source-root
(directory path) 		Path to the root directory of the source code "<config-dir>"
output
(path) 		Directory or file for generating output "<config-dir>/reference-output"
compilation-database
(file path) 		Path to the compilation database

source-root

Path to the root directory of the source code

Path to the root directory of the source code. This path is used as a default for input files and a base for relative paths formed from absolute paths. This should typically be the root directory of the git project, as relative paths formed from it can be used to create links to these source files in the repository. Templates use the base-url option to create links to the source code.

  • Type: directory path
  • Default value: "<config-dir>"

output

Directory or file for generating output

Multipage generators expect a directory. Single page generators expect a file or a directory where the file will be created. If the directory does not exist, it will be created.

  • Type: path
  • Default value: "<config-dir>/reference-output"

compilation-database

Path to the compilation database

Path to the compilation database or a build script to generate it. The compilation database is a JSON file that contains the compiler commands used to build the source code. The compilation database is used to extract the compiler flags and the source files used to build the source code and extract symbols. This option also accepts the path to a build script such as CMakeLists.txt to be used to generate the compilation database. In this case, MrDocs will look for CMake in PATH or in CMAKE_ROOT and run the script to generate the compilation database file.

  • Type: file path
  • Default value:

Filters

Filters to include or exclude files and symbols from the documentation

Name Description Default
input
(list of paths) 		Input directories to extract symbols from ["<source-root>/."]
recursive
(boolean) 		Recursively include files from "input" paths true
file-patterns
(list of path-globs) 		File patterns to include ["*.hpp", "*.h", "*.hh", "*.ipp", "*.inc", "*.cpp", "*.cc", "*.cxx", "*.c", "*.hxx"]
exclude
(list of paths) 		Input directories to exclude []
exclude-patterns
(list of path-globs) 		File patterns to exclude []
include-symbols
(list of symbol-globs) 		Symbol patterns to include []
exclude-symbols
(list of symbol-globs) 		Symbol patterns to exclude []
see-below
(list of symbol-globs) 		Exposition only symbols rendered as "see-below". []
implementation-defined
(list of symbol-globs) 		Symbols rendered as "implementation-defined" []

input

Input directories to extract symbols from

Input directories to extract. Only symbols defined in files in these directories are extracted. The paths are relative to the mrdocs configuration file.

  • Type: list of paths
  • Default value: ["<source-root>/."]

recursive

Recursively include files from "input" paths

Recursively include files. When set to true, MrDocs includes files in subdirectories of the input directories. When set to false, MrDocs includes only the files in the input directories.

  • Type: boolean
  • Default value: true

file-patterns

File patterns to include

File patterns to include. Only the files that match these patterns are extracted. The patterns are relative to the input directories.

  • Type: list of path-globs
  • Default value: ["*.hpp", "*.h", "*.hh", "*.ipp", "*.inc", "*.cpp", "*.cc", "*.cxx", "*.c", "*.hxx"]

exclude

Input directories to exclude

Symbols defined in files in these directories are not extracted even if they are in the list of include directories. When relative, the paths are relative to the directory of the mrdocs configuration file. For instance, "include/experimental" will exclude all files in the directory <config-dir>/include/experimental.

  • Type: list of paths
  • Default value: []

exclude-patterns

File patterns to exclude

File patterns to exclude. Files that match these patterns are not extracted even if they are in the list of include directories. The patterns are relative to the configuration file. A single * will match all files in the directory. Double ** will match all files in the directory and its subdirectories.

  • Type: list of path-globs
  • Default value: []

include-symbols

Symbol patterns to include

If any patterns are defined here, only symbols that match one of these patterns are extracted. The patterns are applied to the fully qualified name of the symbol without any leading "::". A single "*" will match all symbols in the namespace. Double "**" will match all symbols in the namespace and its subnamespaces. The patterns also support "?" for any chars, "[<chars>]" for charsets, "[^<chars>]" for inverted charsets, and "{<glob>,...}" for alternatives.

  • Type: list of symbol-globs
  • Default value: []

exclude-symbols

Symbol patterns to exclude

A symbol that matches one of these patterns is not extracted even if whitelisted by "include-symbols". See the documentation for "include-symbols" for the pattern syntax.

  • Type: list of symbol-globs
  • Default value: []

see-below

Exposition only symbols rendered as "see-below".

Symbols that match one of these filters are tagged as "see-below" in the documentation, and so do symbols in scopes tagged as "see-below". This option is used to remove details about symbols that are considered part of the private API of the project but the user might need to interact with. In the documentation page for this symbol, the symbol is exposition only: the synopsis of the implementation is rendered as "see-below" and members of scopes (such as a namespace or record) are not listed. The rest of the documentation is rendered as usual to explain the symbol. See the documentation for "include-symbol" for the pattern syntax.

  • Type: list of symbol-globs
  • Default value: []

implementation-defined

Symbols rendered as "implementation-defined"

Symbols that match one of these filters are tagged as "implementation-defined" in the documentation, and so do symbols in scopes tagged as "implementation-defined". This option is used to exclude symbols from the documentation that are considered part of the private API of the project. An "implementation-defined" symbol has no documentation page in the output. If any other symbol refers to it, the reference is rendered as "implementation-defined". See the documentation for "include-symbol" for the pattern syntax.

  • Type: list of symbol-globs
  • Default value: []

Comment Parsing

Options to control how comments are parsed

MrDocs extracts metadata from the comments in the source code. The following options control how comments are parsed.

Name Description Default
auto-brief
(boolean) 		Use the first line of the comment as the brief true

auto-brief

Use the first line of the comment as the brief

When set to true, MrDocs uses the first line (until the first dot, question mark, or exclamation mark) of the comment as the brief of the symbol. When set to false, a explicit @brief command is required.

  • Type: boolean
  • Default value: true

Metadata Extraction

Metadata and C++ semantic constructs to extract

MrDocs extracts metadata and C++ semantic constructs from the source code to create the documentation. Semantic constructs are patterns not directly represented in the source code AST but can be inferred from the corpus, such as SFINAE. The following options control the extraction of metadata and C++ semantic constructs.

Name Description Default
extract-all
(boolean) 		Extract all symbols true
extract-private
(boolean) 		Extraction policy for private class members false
extract-private-virtual
(boolean) 		Extraction policy for private virtual methods of a class false
extract-private-bases
(boolean) 		Extraction policy for private base classes false
extract-static
(boolean) 		Extraction policy for static members of a file false
extract-local-classes
(boolean) 		Extraction policy for records defined locally in source files true
extract-anonymous-namespaces
(boolean) 		Extraction policy for anonymous namespaces true
extract-empty-namespaces
(boolean) 		Extraction policy for empty namespaces false
inherit-base-members
(enum) 		Determine how derived classes inherit base members "copy-dependencies"
sort-members
(boolean) 		Sort the members of a record or namespace true
sort-members-ctors-1st
(boolean) 		Sort constructors first true
sort-members-dtors-1st
(boolean) 		Sort destructors first true
sort-members-assignment-1st
(boolean) 		Sort assignment operators first true
sort-members-conversion-last
(boolean) 		Sort conversion operators last true
sort-members-relational-last
(boolean) 		Sort relational operators last true

extract-all

Extract all symbols

When set to true, MrDocs extracts all symbols from the source code, even if no documentation is provided. MrDocs can only identify whether a symbol is ultimated documented after extracting information from all translation units. For this reason, when this option is set to false, it's still recommendable to provide file and symbol filters so that only the desired symbols are traversed and stored by MrDocs.

  • Type: boolean
  • Default value: true

extract-private

Extraction policy for private class members

Determine whether private class members should be extracted

  • Type: boolean
  • Default value: false

extract-private-virtual

Extraction policy for private virtual methods of a class

Determine whether private virtual methods of a class should be extracted

  • Type: boolean
  • Default value: false

extract-private-bases

Extraction policy for private base classes

Determine whether private base classes should be extracted

  • Type: boolean
  • Default value: false

extract-static

Extraction policy for static members of a file

Determine whether static members of a file should be extracted. This option does not refer to static members of a class.

  • Type: boolean
  • Default value: false

extract-local-classes

Extraction policy for records defined locally in source files

Determine whether records only defined locally in source files should be extracted.

  • Type: boolean
  • Default value: true

extract-anonymous-namespaces

Extraction policy for anonymous namespaces

Determine whether symbols in anonymous namespaces should be extracted.

  • Type: boolean
  • Default value: true

extract-empty-namespaces

Extraction policy for empty namespaces

Determine whether empty namespaces without documentation should be extracted.

  • Type: boolean
  • Default value: false

inherit-base-members

Determine how derived classes inherit base members

Determine how derived classes inherit members of base classes. When set to never, derived classes do not inherit members of base classes and only the relationship is stored. When set to reference, derived classes list members of base classes but references are still linked to the base class. When set to copy-dependencies, a reference is created by default and a copy is created when the base class is a dependency. When set to copy-all, a copy is created for each base symbol as if it was declared in the derived class. If the base class is a dependency, the extraction mode is copied from the new parent.

  • Type: enum
  • Default value: "copy-dependencies"
  • Allowed values: ["never", "reference", "copy-dependencies", "copy-all"]

sort-members

Sort the members of a record or namespace

When set to true, sort the members of a record or namespace by name and parameters. When set to false, the members are included in the declaration order they are extracted.

  • Type: boolean
  • Default value: true

sort-members-ctors-1st

Sort constructors first

When set to true, constructors are sorted first in the list of members of a record.

  • Type: boolean
  • Default value: true

sort-members-dtors-1st

Sort destructors first

When set to true, destructors are sorted first in the list of members of a record.

  • Type: boolean
  • Default value: true

sort-members-assignment-1st

Sort assignment operators first

When set to true, assignment operators are sorted first in the list of members of a record.

  • Type: boolean
  • Default value: true

sort-members-conversion-last

Sort conversion operators last

When set to true, conversion operators are sorted last in the list of members of a record or namespace.

  • Type: boolean
  • Default value: true

sort-members-relational-last

Sort relational operators last

When set to true, relational operators are sorted last in the list of members of a record or namespace.

  • Type: boolean
  • Default value: true

Semantic Constructs

C++ semantic constructs to extract

Semantic constructs are patterns not directly represented in the source code AST but can be inferred from the corpus, such as SFINAE.

Name Description Default
sfinae
(boolean) 		Detect and reduce SFINAE expressions true
overloads
(boolean) 		Detect and group function overloads true

sfinae

Detect and reduce SFINAE expressions

When set to true, MrDocs detects SFINAE expressions in the source code and extracts them as part of the documentation. Expressions such as std::enable_if<...> are detected, removed, and documented as a requirement. MrDocs uses an algorithm that extracts SFINAE infomation from types by identifying inspecting the primary template and specializations to detect the result type and the controlling expressions in a specialization.

  • Type: boolean
  • Default value: true

overloads

Detect and group function overloads

When set to true, MrDocs detects function overloads and groups them as a single symbol type. The documentation for this new symbol comes from the union of non-ambiguous metadata from the functions.

  • Type: boolean
  • Default value: true

Generators

Generators to create the documentation and their options

Name Description Default
generator
(enum) 		Generator used to create the documentation "adoc"
multipage
(boolean) 		Generate a multipage documentation true
base-url
(string) 		Base URL for links to source code
addons
(path) 		Path to the Addons directory "<mrdocs-root>/share/mrdocs/addons"
tagfile
(file path) 		Path for the tagfile "<output-dir>/reference.tag.xml"
legible-names
(boolean) 		Use legible names true
embedded
(boolean) 		Output an embeddable document false
show-namespaces
(boolean) 		Show namespace pages in the documentation true

generator

Generator used to create the documentation

The generator is responsible for creating the documentation from the extracted symbols. The generator uses the extracted symbols and the templates to create the documentation. The generator can create different types of documentation such as HTML, XML, and AsciiDoc.

  • Type: enum
  • Default value: "adoc"
  • Allowed values: ["adoc", "html", "xml"]

multipage

Generate a multipage documentation

Generates a multipage documentation. The output directory must be a directory. This option acts as a hint to the generator to create a multipage documentation. Whether the hint is followed or not depends on the generator.

  • Type: boolean
  • Default value: true

base-url

Base URL for links to source code

Base URL for links to source code. The base URL is used to create links to the source code in the documentation. The base URL is combined with the path to the source file to create the link.

  • Type: string
  • Default value:

addons

Path to the Addons directory

Path to the Addons directory. The Addons directory contains the template files used by generators to create the documentation. When a custom Addons directory is not specified, the default templates are used. The default templates are located at the share/mrdocs/addons directory of the MrDocs installation. Users can create custom templates by copying the default templates to a custom directory and specifying the custom directory using this option.

  • Type: path
  • Default value: "<mrdocs-root>/share/mrdocs/addons"

tagfile

Path for the tagfile

Specifies the full path (filename) where the generated tagfile should be saved. If left empty, no tagfile will be generated.

  • Type: file path
  • Default value: "<output-dir>/reference.tag.xml"

legible-names

Use legible names

Use legible names for ids in the documentation. When set to true, MrDocs uses legible names for symbols in the documentation. These are symbols that are legible but still safe for URLs. When the option is set to false, MrDocs uses a hash of the symbol ID.

  • Type: boolean
  • Default value: true

embedded

Output an embeddable document

Output an embeddable document, which excludes the header, the footer, and everything outside the body of the document. This option is useful for producing documents that can be inserted into an external template.

  • Type: boolean
  • Default value: false

show-namespaces

Show namespace pages in the documentation

When set to true, MrDocs creates a page for each namespace in the documentation.

  • Type: boolean
  • Default value: true

Build options

Options for building the source code

When MrDocs is responsible to running the build scripts and generating the compilation database, these options are used to build the source code.

Name Description Default
cmake
(string) 		CMake arguments when generating the compilation database from CMakeLists.txt
defines
(list of strings) 		Additional defines passed to the compiler []
use-system-stdlib
(boolean) 		Use the system C++ standard library false
stdlib-includes
(list of paths) 		C++ Standard Library include paths ["<mrdocs-root>/share/mrdocs/headers/libcxx", "<mrdocs-root>/share/mrdocs/headers/clang"]
use-system-libc
(boolean) 		Use the system C standard library false
libc-includes
(list of paths) 		Standard Library include paths ["<mrdocs-root>/share/mrdocs/headers/libc-stubs"]
system-includes
(list of paths) 		System include paths []
includes
(list of paths) 		Include paths []

cmake

CMake arguments when generating the compilation database from CMakeLists.txt

When the compilation-database option is a CMakeLists.txt file, these arguments are passed to the cmake command to generate the compilation_database.json.

  • Type: string
  • Default value:

defines

Additional defines passed to the compiler

Additional defines passed to the compiler when building the source code. These defines are added to the compilation database regardless of the strategy to generate it.

  • Type: list of strings
  • Default value: []

use-system-stdlib

Use the system C++ standard library

To achieve reproducible results, MrDocs bundles the LibC++ headers. To use the C++ standard library available in the system instead, set this option to true.

  • Type: boolean
  • Default value: false

stdlib-includes

C++ Standard Library include paths

When use-system-stdlib is disabled, the C++ standard library headers are available in these paths.

  • Type: list of paths
  • Default value: ["<mrdocs-root>/share/mrdocs/headers/libcxx", "<mrdocs-root>/share/mrdocs/headers/clang"]

use-system-libc

Use the system C standard library

To achieve reproducible results, MrDocs bundles the LibC headers with its definitions. To use the C standard library available in the system instead, set this option to true.

  • Type: boolean
  • Default value: false

libc-includes

Standard Library include paths

When use-system-libc is disabled, the C standard library headers are available in these paths.

  • Type: list of paths
  • Default value: ["<mrdocs-root>/share/mrdocs/headers/libc-stubs"]

system-includes

System include paths

System include paths. These paths are used to add directories to the system include search path. The system include search path is used to search for system headers. The system headers are headers that are provided by the system and are not part of the project. The system headers are used to provide the standard library headers and other system headers. The system headers are not part of the project and are not checked for warnings and errors.

  • Type: list of paths
  • Default value: []

includes

Include paths

Include paths. These paths are used to add directories to the include search path. The include search path is used to search for headers. The headers are used to provide declarations and definitions of symbols. The headers are part of the project and are checked for warnings and errors.

  • Type: list of paths
  • Default value: []

Warnings

Warnings and progress messages

Name Description Default
verbose
(boolean) 		Verbose output false
report
(unsigned integer)
(Deprecated) 		The minimum reporting level -1
log-level
(enum) 		The minimum reporting level "info"
warnings
(boolean) 		Enable warning messages true
warn-if-undocumented
(boolean) 		Warn if symbols are not documented true
warn-if-doc-error
(boolean) 		Warn if documentation has errors true
warn-no-paramdoc
(boolean) 		Warn if parameters are not documented true
warn-unnamed-param
(boolean) 		Warn if documented functions have unnamed parameters false
warn-if-undoc-enum-val
(boolean) 		Warn if enum values are not documented true
warn-broken-ref
(boolean) 		Warn if a documentation reference is broken true
warn-as-error
(boolean) 		Treat warnings as errors false

verbose

Verbose output

Verbose output. When set to true, MrDocs outputs additional information during the generation of the documentation.

  • Type: boolean
  • Default value: false

report

The minimum reporting level

The reporting level determines the amount of information displayed during the generation of the documentation. The value -1 delegates the decision to the log-level option.

  • Deprecated: Use log-level instead
  • Type: unsigned integer
  • Default value: -1
  • Minimum value: -1
  • Maximum value: 5

log-level

The minimum reporting level

The reporting level determines the amount of information displayed during the generation of the documentation.

  • Type: enum
  • Default value: "info"
  • Allowed values: ["trace", "debug", "info", "warn", "error", "fatal"]

warnings

Enable warning messages

When set to true, MrDocs outputs warning messages during the generation of the documentation. It is usually recommended to enable warnings while writing the documentation.

  • Type: boolean
  • Default value: true

warn-if-undocumented

Warn if symbols are not documented

When set to true, MrDocs outputs a warning message if a symbol that passes all filters is not documented.

  • Type: boolean
  • Default value: true

warn-if-doc-error

Warn if documentation has errors

When set to true, MrDocs outputs a warning message if the documentation of a symbol has errors such as duplicate parameters and parameters that don't exist.

  • Type: boolean
  • Default value: true

warn-no-paramdoc

Warn if parameters are not documented

When set to true, MrDocs outputs a warning message if a named function parameter is not documented.

  • Type: boolean
  • Default value: true

warn-unnamed-param

Warn if documented functions have unnamed parameters

When set to true, MrDocs outputs a warning message if a documented function has a parameter that is not named.

  • Type: boolean
  • Default value: false

warn-if-undoc-enum-val

Warn if enum values are not documented

When set to true, MrDocs outputs a warning message if an enum value is not documented.

  • Type: boolean
  • Default value: true

warn-broken-ref

Warn if a documentation reference is broken

When set to true, MrDocs outputs a warning message if a reference in the documentation is broken.

  • Type: boolean
  • Default value: true

warn-as-error

Treat warnings as errors

When set to true, MrDocs treats warnings as errors and stops the generation of the documentation.

  • Type: boolean
  • Default value: false

Miscellaneous

Miscellaneous options

Name Description Default
concurrency
(unsigned integer)
(Command line only) 		Number of threads to use 0
ignore-map-errors
(boolean) 		Continue if files are not mapped correctly false
ignore-failures
(boolean) 		Whether AST visitation failures should not stop the program false

concurrency

Number of threads to use

The desired level of concurrency: 0 for hardware-suggested.

  • Type: unsigned integer
  • Command line only
  • Default value: 0
  • Minimum value: 0

ignore-map-errors

Continue if files are not mapped correctly

When set to true, MrDocs continues to generate the documentation even if some files are not mapped correctly. Files are not mapped correctly when the source file is not found or the compilation database does not contain the compiler flags for the source file.

  • Type: boolean
  • Default value: false

ignore-failures

Whether AST visitation failures should not stop the program

When set to true, MrDocs continues to generate the documentation even if there are AST visitation failures. AST visitation failures occur when the source code contains constructs that are not supported by MrDocs.

  • Type: boolean
  • Default value: false