Options Reference

Inputs

Inputs, paths, and the toolchain used to compile them

These options tell Mr.Docs which sources to read, where to write the result, and how to compile the code. They cover the command-line inputs and configuration file, the source root and output location, the compilation database, and the include paths, preprocessor defines, and standard-library and toolchain settings the compiler needs to parse the sources.

Name Description Default
cmd-line-inputs
(list of paths)
(Command line only) 		Configuration or compilation database files []
config
(file path)
(Required, Command line only) 		Mr.Docs configuration file "<cwd>/mrdocs.yml"
source-root
(directory path) 		Path to the root directory of the source code "<config-dir>"
compilation-database
(file path) 		Path to the compilation database
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 true
stdlib-includes
(list of paths) 		C++ Standard Library include paths ["<mrdocs-root>/share/mrdocs/headers/libcxx"]
use-system-libc
(boolean) 		Use the system C standard library true
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 []

cmd-line-inputs

Configuration or compilation database files

Positional inputs that drive the run. Each path is dispatched by file name: an input ending in mrdocs.yml is read as a configuration file, and an input ending in compile_commands.json or CMakeLists.txt is read as a compilation database. The dispatch is a convenience; prefer the explicit config and compilation-database flags so the invocation is unambiguous and easier to read in scripts and CI logs.

  • 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

Mr.Docs configuration file

A YAML file holding the options for the run: the source code, the output directory, the compilation database, the generator, and the filters. MrDocs reads it and applies the options it finds.

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

source-root

Path to the root directory of the source code

The root directory of the source tree. It is the default location for input files and the base for the relative paths MrDocs forms from absolute ones. Set it to the root of the git project so those relative paths can link back to the source files in the repository; templates build those links from the base-url option.

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

compilation-database

Path to the compilation database

The path to a compilation database, or to a build script that generates one. A compilation database is a JSON file of the compiler commands that build the source; MrDocs reads the compiler flags and source files from it to extract symbols. You can also pass a build script such as CMakeLists.txt: MrDocs then looks for CMake on PATH or in CMAKE_ROOT, runs the script, and uses the database it produces.

  • Type: file path
  • Default value:

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: true

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"]

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: true

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

Directories added to the system header search path. Headers found there are treated as system headers: they come from outside the project and are not checked for warnings or errors. The standard library and other external headers usually live here.

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

includes

Include paths

Directories added to the header search path. Headers found there are part of the project and are checked for warnings and errors. Reach for this option when MrDocs cannot find a header your code includes.

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

Filters

Which symbols are documented, and which are hidden

These options decide which symbols enter the documentation corpus and how the ones that do appear. They filter by qualified name, by category (private members, undocumented declarations, friends, anonymous namespaces, and so on), by location on disk, and by marking specific symbols as private without dropping them from the corpus.

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" []
auto-function-objects
(boolean) 		Automatically detect algorithm function objects true
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
extract-implicit-specializations
(boolean) 		Implicit template specializations used as base classes are extracted as dependencies true
extract-friends
(boolean) 		Extraction policy for friend functions and classes true

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. Inclusion is generous about symlinks: a file counts as being inside an input directory when its path matches the directory either as written or by its real (symlink-resolved) location.

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

Example

include/libavcodec/avcodec.h
/** Allocate a new packet on the heap. */
int av_packet_alloc(void);

/** Release a packet allocated with `av_packet_alloc`. */
void av_packet_free(void);
include/libavformat/avformat.h
// Filtered out: `input: include/libavcodec` scopes extraction to that
// directory, so the format-library functions never enter the corpus.
// The directory matters because both libraries put their declarations
// at global scope under the same `av_*` prefix, so a name-based filter
// could not distinguish them.
int av_open_input_file(void);
void av_close_input_file(void);
input.cpp
#include <libavcodec/avcodec.h>
#include <libavformat/avformat.h>
mrdocs.yml
input:
  - include/libavcodec
Preview·input

av_packet_alloc

Allocate a new packet on the heap.

Synopsis

Declared in <libavcodec/avcodec.h>

int
av_packet_alloc();

av_packet_free

Release a packet allocated with av_packet_alloc.

Synopsis

Declared in <libavcodec/avcodec.h>

void
av_packet_free();

recursive

Recursively include files from "input" paths

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

  • Type: boolean
  • Default value: true

Example

include/cli/detail/tokens.hpp
namespace cli::detail {
// Filtered out: lives in a subdirectory that `recursive: false`
// skips, so `cli::detail::tokenize` never enters the corpus.
void tokenize(char const* arg);
}
include/cli/parse.hpp
namespace cli {
/** Parses command-line arguments into an option set. */
void parse(int argc, char** argv);
}
recursive.cpp
#include <cli/parse.hpp>
#include <cli/detail/tokens.hpp>
mrdocs.yml
input:
  - include/cli
recursive: false
Preview·recursive

cli::parse

Parses command‐line arguments into an option set.

Synopsis

Declared in <cli/parse.hpp>

void
parse(
    int argc,
    char** argv);

file-patterns

File patterns to include

Only files whose names match these glob 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. Exclusion is strict about symlinks: it matches the file path only as written and does not resolve symlinks.

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

Example

include/httpd/server.hpp
namespace httpd {

/** Start the HTTP server on `port`. */
void start(int port);

/** Stop the running server. */
void stop();

}
include/zlib/zlib.h

// Vendored copy of zlib's public API. Documented upstream at
// https://zlib.net/, not here. `exclude: include/zlib` keeps the
// vendored library out of the rendered docs so it does not appear
// alongside the httpd API.

/* Compress `src` into `dst` using DEFLATE. */
int compress2(unsigned char* dst, unsigned long* dstLen,
              unsigned char const* src, unsigned long srcLen,
              int level);

/* Decompress a DEFLATE-compressed buffer. */
int uncompress(unsigned char* dst, unsigned long* dstLen,
               unsigned char const* src, unsigned long srcLen);
exclude.cpp
#include <httpd/server.hpp>
#include <zlib/zlib.h>
mrdocs.yml
exclude:
  - include/zlib
Preview·exclude

httpd::start

Start the HTTP server on port.

Synopsis

Declared in <httpd/server.hpp>

void
start(int port);

httpd::stop

Stop the running server.

Synopsis

Declared in <httpd/server.hpp>

void
stop();

exclude-patterns

File patterns to exclude

Files matching these glob patterns are skipped, even when they sit inside an included directory. The patterns are relative to the configuration file. A single * matches everything in a directory; ** matches everything in a directory and its subdirectories.

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

Example

include/payments/_generated/messages.hpp
namespace payments::gen {
struct AuthorizeRequest {};
struct AuthorizeResponse {};
}
include/payments/payments.hpp
namespace payments {

/** Authorize a payment of `amount` against `account`. */
bool authorize(char const* account, double amount);

}
include/storage/_generated/messages.hpp

// Generated by the build (protoc, gRPC, OpenAPI, …); do not edit by
// hand. Every component in this project keeps its generated headers
// next to the hand-written ones under a `_generated/` subdirectory,
// so `exclude-patterns: '**/_generated/**'` drops them all at once.

namespace storage::gen {
struct PutRequest {};
struct PutResponse {};
}
include/storage/storage.hpp
namespace storage {

/** Persist a value under `key`. */
void put(char const* key, char const* value);

}
exclude-patterns.cpp
#include <storage/storage.hpp>
#include <storage/_generated/messages.hpp>
#include <payments/payments.hpp>
#include <payments/_generated/messages.hpp>
mrdocs.yml
exclude-patterns:
  - '**/_generated/**'
Preview·exclude-patterns

payments::authorize

Authorize a payment of amount against account.

Synopsis

Declared in <payments/payments.hpp>

bool
authorize(
    char const* account,
    double amount);

storage::put

Persist a value under key.

Synopsis

Declared in <storage/storage.hpp>

void
put(
    char const* key,
    char const* 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: []

Example

Input
namespace lib {
namespace detail {
/// An internal helper that should not appear in the docs.
int helper();
}

/// The library's only public entry point.
int run();
}
mrdocs.yml
include-symbols:
  - 'lib::run'
Preview·include-symbols

lib::run

The library's only public entry point.

Synopsis

Declared in <include‐symbols.cpp>

int
run();

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: []

Example

include/jzon/extra/utilities.hpp
namespace jzon::extra {

// Filtered out: `exclude-symbols: 'jzon::extra::**'` drops these
// symbols by qualified name, so the `jzon::extra` namespace and its
// members never enter the rendered docs.
void enable_trace();
void disable_trace();

}
include/jzon/parser.hpp
namespace jzon {

/** Validate that the document is well-formed JSON.

    Parses `source` without constructing a value tree, reporting only
    whether the input conforms to RFC 8259. Comments and trailing
    commas are rejected.

    @param source A null-terminated UTF-8 JSON document.
    @return `true` if the document is syntactically valid JSON, `false`
            if any syntactic error is encountered.
*/
bool validate(char const* source);

}
exclude-symbols.cpp
#include <jzon/parser.hpp>
#include <jzon/extra/utilities.hpp>
mrdocs.yml
exclude-symbols:
  - 'jzon::extra::**'
Preview·exclude-symbols

jzon::validate

Validate that the document is well‐formed JSON.

Synopsis

Declared in <jzon/parser.hpp>

bool
validate(char const* source);
Description

Parses source without constructing a value tree, reporting only whether the input conforms to RFC 8259. Comments and trailing commas are rejected.

Return Value

true if the document is syntactically valid JSON, false if any syntactic error is encountered.

Parameters

Name

Description

source

A null‐terminated UTF‐8 JSON document.

see-below

Exposition only symbols rendered as "see-below".

Symbols matching these filters, and symbols in scopes that match, are tagged "see-below" in the documentation. Use it for symbols that belong to the project's private API but that users still interact with. On such a symbol's page the implementation synopsis is rendered as "see-below" and the members of a scope, such as a namespace or record, are not listed, while the rest of the documentation appears as usual. See include-symbols for the pattern syntax.

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

Example

include/netz/buffer_view.hpp
namespace netz {

/** A non-owning view of a contiguous byte range.

    Used as the parameter and return type for the framing helpers in
    `netz::stream` and as the buffer surface presented to async read
    handlers. Stores a pointer and a length, and does not extend the
    lifetime of the storage it refers to.
*/
class buffer_view
{
public:
    unsigned char const* data() const noexcept;
    unsigned long size() const noexcept;
};

}
include/netz/stream.hpp
namespace netz {

/** Locate the first complete packet at the start of the buffer.

    Scans `input` for a frame boundary. The returned view aliases the
    same memory as `input`, so the storage behind `input` must outlive
    the returned view.

    @param input Bytes received from the stream, up to the caller's
                 current fill mark.
    @return A view of the bytes belonging to the first packet, or an
            empty view if no complete packet is present yet.
*/
buffer_view first_packet(buffer_view input);

}
see-below.cpp
#include <netz/stream.hpp>
mrdocs.yml
see-below:
  - 'netz::buffer_view'
Preview·see-below

netz::buffer_view

A non‐owning view of a contiguous byte range.

Synopsis

Declared in <netz/buffer_view.hpp>

class buffer_view { /* see-below */ };
Description

Used as the parameter and return type for the framing helpers in netz::stream and as the buffer surface presented to async read handlers. Stores a pointer and a length, and does not extend the lifetime of the storage it refers to.

netz::first_packet

Locate the first complete packet at the start of the buffer.

Synopsis

Declared in <netz/stream.hpp>

buffer_view
first_packet(buffer_view input);
Description

Scans input for a frame boundary. The returned view aliases the same memory as input, so the storage behind input must outlive the returned view.

Return Value

A view of the bytes belonging to the first packet, or an empty view if no complete packet is present yet.

Parameters

Name

Description

input

Bytes received from the stream, up to the caller's current fill mark.

implementation-defined

Symbols rendered as "implementation-defined"

Symbols matching these filters, and symbols in scopes that match, are tagged "implementation-defined". Use it for symbols that belong to the project's private API. An "implementation-defined" symbol has no page of its own, and any reference to it renders as "implementation-defined". See include-symbols for the pattern syntax.

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

Example

include/logr/detail/scope_token.hpp
namespace logr::detail {
struct scope_token { ~scope_token(); };
}
include/logr/log.hpp
namespace logr {

/** Attach a key/value pair to every log line in the current scope.

    The context stays attached until the returned token is destroyed.
    Hold it in `auto`; nested contexts stack and unwind in reverse order.

    @par Example
    @code
    void handle_request(request const& req) {
        auto ctx = logr::scoped_context("request_id", req.id);
        do_work(req);
    }
    @endcode

    @param key   The context name surfaced on each log line.
    @param value The context value surfaced on each log line.
    @return An opaque RAII token whose lifetime governs how long the pair
            stays attached. The type is implementation-defined; store it
            in `auto`.
*/
detail::scope_token scoped_context(char const* key, char const* value);

}
implementation-defined.cpp
#include <logr/log.hpp>
mrdocs.yml
implementation-defined:
  - 'logr::detail::**'
Preview·implementation-defined

logr::scoped_context

Attach a key/value pair to every log line in the current scope.

Synopsis

Declared in <logr/log.hpp>

/* implementation-defined */
scoped_context(
    char const* key,
    char const* value);
Description

The context stays attached until the returned token is destroyed. Hold it in auto; nested contexts stack and unwind in reverse order.

Example
void handle_request(request const& req) {
    auto ctx = logr::scoped_context("request_id", req.id);
    do_work(req);
}
Return Value

An opaque RAII token whose lifetime governs how long the pair stays attached. The type is implementation‐defined; store it in auto.

Parameters

Name

Description

key

The context name surfaced on each log line.

value

The context value surfaced on each log line.

auto-function-objects

Automatically detect algorithm function objects

When true, Mr.Docs automatically detects algorithm function objects (informally known as niebloids): variables whose type is a record whose only public non-special members are operator() overloads. Set to false to disable auto-detection and rely solely on the @functionobject/@functor doc command. The @functionobject command is still useful when auto-detection is enabled, to force treatment of types that fail auto-detection (e.g. because they have extra public members); it may be placed on the variable or on the function-object record. When a variable is treated as an algorithm function object, its documentation comes from the record's operator() overloads, falling back to the variable's own doc comment when operator() is undocumented; the record's own doc comment is not used.

  • Type: boolean
  • Default value: true

Example

include/numerics/clamp.hpp
namespace numerics {

struct clamp_fn
{
    /** Constrain a value to the inclusive range `[lo, hi]`.

        Returns `lo` when `v < lo`, `hi` when `hi < v`, otherwise `v`.
        Behavior is undefined if `hi < lo`.

        @tparam T  A type comparable with `operator<`.
        @param  v  The value to constrain.
        @param  lo The inclusive lower bound.
        @param  hi The inclusive upper bound.
        @return A copy of `v`, `lo`, or `hi`, whichever lies within the range.
    */
    template <class T>
    T operator()(T const& v, T const& lo, T const& hi) const;
};

inline constexpr clamp_fn clamp = {};

}
auto-function-objects.cpp
#include <numerics/clamp.hpp>
mrdocs.yml
auto-function-objects: true
Preview·auto-function-objects

numerics::clamp

Constrain a value to the inclusive range [lo, hi].

Synopsis

Declared in <numerics/clamp.hpp>

template<class T>
T
clamp(
    T const& v,
    T const& lo,
    T const& hi);
Note

This function is defined as an Algorithm Function Object (AFO).
Description

Returns lo when v < lo, hi when hi < v, otherwise v. Behavior is undefined if hi < lo.

Return Value

A copy of v, lo, or hi, whichever lies within the range.

Template Parameters

Name

Description

T

A type comparable with operator<.
Parameters

Name

Description

v

The value to constrain.

lo

The inclusive lower bound.

hi

The inclusive upper bound.

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

Example

Input
/// A documented function.
void documented();

// An undocumented function. The default `extract-all: true`
// would pull it in even without a doc comment; setting
// `extract-all: false` hides it.
void undocumented();
mrdocs.yml
extract-all: false
Preview·extract-all

documented

A documented function.

Synopsis

Declared in <extract‐all.cpp>

void
documented();

extract-private

Extraction policy for private class members

Determine whether private class members should be extracted

  • Type: boolean
  • Default value: false

Example

Input
/// A class with both public and private members.
class widget
{
public:
    /// Display the widget.
    void show();

private:
    /// An internal counter.
    int count;
};
mrdocs.yml
extract-private: true
Preview·extract-private

widget

A class with both public and private members.

Synopsis

Declared in <extract‐private.cpp>

class widget;
Member Functions

Name

Description

show

Display the widget.
Private Data Members

Name

Description

count

An internal counter.

widget::show

Display the widget.

Synopsis

Declared in <extract‐private.cpp>

void
show();

widget::count

An internal counter.

Synopsis

Declared in <extract‐private.cpp>

int count;

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

Example

Input
/// A base class declaring a virtual `draw` method.
struct shape
{
    virtual ~shape() = default;
    /// Render the shape.
    virtual void draw() = 0;
};

/// A circle implementation.
class circle : public shape
{
public:
    /// Construct a circle of the given radius.
    explicit circle(double r);

private:
    /// The private override of `shape::draw`.
    void draw() override;

    double radius;
};
mrdocs.yml
extract-private-virtual: true
Preview·extract-private-virtual

circle

A circle implementation.

Synopsis

Declared in <extract‐private‐virtual.cpp>

class circle
    : public shape
Base Classes

Name

Description

shape

A base class declaring a virtual draw method.
Member Functions

Name

Description

circle [constructor]

Construct a circle of the given radius.

draw [virtual]

Render the shape.
Private Member Functions

Name

Description

draw [virtual]

The private override of shape::draw.

circle::circle

Construct a circle of the given radius.

Synopsis

Declared in <extract‐private‐virtual.cpp>

explicit
circle(double r);
Parameters

Name

Description

r

The value to construct from

circle::draw

The private override of shape::draw.

Synopsis

Declared in <extract‐private‐virtual.cpp>

virtual
void
draw() override;

shape

A base class declaring a virtual draw method.

Synopsis

Declared in <extract‐private‐virtual.cpp>

struct shape;
Member Functions

Name

Description

~shape [destructor] [virtual]

Destructor

draw [virtual]

Render the shape.
Derived Classes

Name

Description

circle

A circle implementation.

shape::~shape

Destructor

Synopsis

Declared in <extract‐private‐virtual.cpp>

constexpr
virtual
~shape() = default;

shape::draw

Render the shape.

Synopsis

Declared in <extract‐private‐virtual.cpp>

virtual
void
draw() = 0;

extract-private-bases

Extraction policy for private base classes

Determine whether private base classes should be extracted

  • Type: boolean
  • Default value: false

Example

Input
/// A logger mixin.
class logger
{
public:
    /// Write a message to the log.
    void log(const char* msg);
};

/// A widget that privately inherits from `logger`
/// for the logging implementation.
class widget : private logger
{
public:
    /// Render the widget and write a log entry.
    void show();
};
mrdocs.yml
extract-private-bases: true
Preview·extract-private-bases

logger

A logger mixin.

Synopsis

Declared in <extract‐private‐bases.cpp>

class logger;
Member Functions

Name

Description

log

Write a message to the log.

logger::log

Write a message to the log.

Synopsis

Declared in <extract‐private‐bases.cpp>

void
log(char const* msg);

widget

A widget that privately inherits from logger for the logging implementation.

Synopsis

Declared in <extract‐private‐bases.cpp>

class widget
    : logger
Member Functions

Name

Description

show

Render the widget and write a log entry.

widget::show

Render the widget and write a log entry.

Synopsis

Declared in <extract‐private‐bases.cpp>

void
show();

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

Example

Input
/// A regular free function.
void run();

/// A static helper with internal linkage. With
/// `extract-static: true` it appears in the docs.
static void warm_caches();
mrdocs.yml
extract-static: true
Preview·extract-static

run

A regular free function.

Synopsis

Declared in <extract‐static.cpp>

void
run();

warm_caches

A static helper with internal linkage. With extract‐static: true it appears in the docs.

Synopsis

Declared in <extract‐static.cpp>

static
void
warm_caches();

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

Example

Input
/// A function whose local helper class is part of
/// the public interface (its instances escape via
/// the returned visitor).
inline void each()
{
    /// Local visitor type.
    struct visitor
    {
        void operator()(int) {}
    };
    visitor{}(0);
}
mrdocs.yml
extract-local-classes: true
Preview·extract-local-classes

each

A function whose local helper class is part of the public interface (its instances escape via the returned visitor).

Synopsis

Declared in <extract‐local‐classes.cpp>

void
each();

extract-anonymous-namespaces

Extraction policy for anonymous namespaces

Determine whether symbols in anonymous namespaces should be extracted.

  • Type: boolean
  • Default value: true

Example

Input
namespace lib {

/// A regular public function.
void run();

namespace {
/// A helper with translation-unit-local linkage. With
/// `extract-anonymous-namespaces: true` it shows up
/// in the docs.
void warm_caches();
}

}
mrdocs.yml
extract-anonymous-namespaces: true
Preview·extract-anonymous-namespaces

lib::run

A regular public function.

Synopsis

Declared in <extract‐anonymous‐namespaces.cpp>

void
run();

lib::warm_caches

A helper with translation‐unit‐local linkage. With extract‐anonymous‐namespaces: true it shows up in the docs.

Synopsis

Declared in <extract‐anonymous‐namespaces.cpp>

void
warm_caches();

extract-empty-namespaces

Extraction policy for empty namespaces

Determine whether empty namespaces without documentation should be extracted.

  • Type: boolean
  • Default value: false

Example

Input
namespace lib {
/** Greet the user by name. */
void greet(char const* name);
}

// Empty namespace reserved for future expansion. With
// `extract-empty-namespaces: true` it still appears in the docs.
namespace lib::experimental {}
mrdocs.yml
extract-empty-namespaces: true
show-namespaces: true
Preview·extract-empty-namespaces

Global namespace

Namespaces

Name

lib

lib

Namespaces

Name

experimental
Functions

Name

Description

greet

Greet the user by name.

lib::experimental

lib::greet

Greet the user by name.

Synopsis

Declared in <extract‐empty‐namespaces.cpp>

void
greet(char const* name);

extract-implicit-specializations

Implicit template specializations used as base classes are extracted as dependencies

When set to true, MrDocs extracts implicit template specializations that appear as base classes, treating them as dependencies. This gives it the metadata it needs to resolve the derived class's inherited members, as controlled by the inherit-base-members option.

  • Type: boolean
  • Default value: true

Example

Input
/// A simple container template.
template <class T>
struct box
{
    /// The contained value.
    T value;
};

/// Uses `box<int>`. With
/// `extract-implicit-specializations: true`, that
/// implicit instantiation shows up in the docs as
/// `box<int>` alongside the primary template.
box<int> make_int_box(int v);
mrdocs.yml
extract-implicit-specializations: true
Preview·extract-implicit-specializations

box

A simple container template.

Synopsis

Declared in <extract‐implicit‐specializations.cpp>

template<class T>
struct box;
Data Members

Name

Description

value

The contained value.
Non-Member Functions

Name

Description

make_int_box

Uses box<int>. With extract‐implicit‐specializations: true, that implicit instantiation shows up in the docs as box<int> alongside the primary template.

box::value

The contained value.

Synopsis

Declared in <extract‐implicit‐specializations.cpp>

T value;

make_int_box

Uses box<int>. With extract‐implicit‐specializations: true, that implicit instantiation shows up in the docs as box<int> alongside the primary template.

Synopsis

Declared in <extract‐implicit‐specializations.cpp>

box<int>
make_int_box(int v);
Return Value

A simple container template.

extract-friends

Extraction policy for friend functions and classes

Determine whether friend functions and classes should be extracted. When set to true, MrDocs extracts friend functions and classes. When set to false, friend functions and classes are not extracted.

  • Type: boolean
  • Default value: true

Example

Input
/// A point in 2D.
struct point
{
    double x;
    double y;

    /// Equality comparison, declared as a friend so it
    /// participates in ADL.
    friend bool operator==(point a, point b);
};
mrdocs.yml
extract-friends: true
Preview·extract-friends

point

A point in 2D.

Synopsis

Declared in <extract‐friends.cpp>

struct point;
Data Members

Name

x

y
Friends

Name

Description

operator==

Equality comparison, declared as a friend so it participates in ADL.

point::x

Synopsis

Declared in <extract‐friends.cpp>

double x;

point::y

Synopsis

Declared in <extract‐friends.cpp>

double y;

operator==

Equality comparison, declared as a friend so it participates in ADL.

Synopsis

Declared in <extract‐friends.cpp>

bool
operator==(
    point a,
    point b);
Return Value

true if the objects are equal, false otherwise

Parameters

Name

Description

a

The left operand

b

The right operand

Extraction

How extracted symbols are arranged and what MrDocs infers from them

These options control how the documentation set is presented once the filters have decided what enters it: which inherited members are shown on a class page, the order members appear in, how related declarations are grouped (overload sets, SFINAE expressions, function objects), what MrDocs infers from doc comments (briefs, relations, function metadata), and tolerance for headers the compiler cannot find.

Name Description Default
inherit-base-members
(enum) 		Determine how derived classes inherit base members "copy-dependencies"
sort-members
(boolean) 		Sort the members of a record true
sort-members-by
(enum) 		Determine how members of a record are sorted "name"
sort-namespace-members-by
(enum) 		Determine how members of a namespace are sorted "name"
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
sfinae
(boolean) 		Detect and reduce SFINAE expressions true
overloads
(boolean) 		Detect and group function overloads true
missing-include-prefixes
(list of strings) 		Include path prefixes allowed to be missing []
missing-include-shims
(map) 		Shims for forgiven missing include files {}
auto-brief
(boolean) 		Use the first line of the comment as the brief true
auto-relates
(boolean) 		Automatically find non-member functions true
auto-function-metadata
(boolean) 		Automatically provide missing documentation for special functions and trivial metadata true

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"]

Example

Input
/// A base shape with one operation.
struct shape
{
    /// Render the shape to the screen.
    void draw();
};

/// A circle. The `draw` from `shape` is inherited
/// and listed on the circle's page too.
struct circle : shape
{
    /// Construct a circle of the given radius.
    explicit circle(double r);
};
mrdocs.yml
inherit-base-members: copy-all
Preview·inherit-base-members

circle

A circle. The draw from shape is inherited and listed on the circle's page too.

Synopsis

Declared in <inherit‐base‐members.cpp>

struct circle
    : shape
Base Classes

Name

Description

shape

A base shape with one operation.
Member Functions

Name

Description

circle [constructor]

Construct a circle of the given radius.

draw

Render the shape to the screen.

circle::circle

Construct a circle of the given radius.

Synopsis

Declared in <inherit‐base‐members.cpp>

explicit
circle(double r);
Parameters

Name

Description

r

The value to construct from

circle::draw

Render the shape to the screen.

Synopsis

Declared in <inherit‐base‐members.cpp>

void
draw();

shape

A base shape with one operation.

Synopsis

Declared in <inherit‐base‐members.cpp>

struct shape;
Member Functions

Name

Description

draw

Render the shape to the screen.
Derived Classes

Name

Description

circle

A circle. The draw from shape is inherited and listed on the circle's page too.

shape::draw

Render the shape to the screen.

Synopsis

Declared in <inherit‐base‐members.cpp>

void
draw();

sort-members

Sort the members of a record

When set to true, sort the members of a record by the criterion determined in the sort-members-by option. When set to false, the members are included in the declaration order they are extracted.

  • Type: boolean
  • Default value: true

Example

Input
/// A class declared with members in deliberately
/// scattered order to show how sorting affects the
/// rendered member list.
struct gadget
{
    /// Refresh the gadget.
    void refresh();
    /// Construct a gadget.
    gadget();
    /// Hide the gadget.
    void hide();
    /// Show the gadget.
    void show();
    /// Destroy the gadget.
    ~gadget();
};
mrdocs.yml
sort-members: true
Preview·sort-members

gadget

A class declared with members in deliberately scattered order to show how sorting affects the rendered member list.

Synopsis

Declared in <sort‐members.cpp>

struct gadget;
Member Functions

Name

Description

gadget [constructor]

Construct a gadget.

~gadget [destructor]

Destroy the gadget.

hide

Hide the gadget.

refresh

Refresh the gadget.

show

Show the gadget.

gadget::gadget

Construct a gadget.

Synopsis

Declared in <sort‐members.cpp>

gadget();

gadget::~gadget

Destroy the gadget.

Synopsis

Declared in <sort‐members.cpp>

~gadget();

gadget::hide

Hide the gadget.

Synopsis

Declared in <sort‐members.cpp>

void
hide();

gadget::refresh

Refresh the gadget.

Synopsis

Declared in <sort‐members.cpp>

void
refresh();

gadget::show

Show the gadget.

Synopsis

Declared in <sort‐members.cpp>

void
show();

sort-members-by

Determine how members of a record are sorted

If sort-members is set to true, determine how members of a record are sorted. When set to name, members are sorted by name. When set to location, members are sorted by their primary location in the source code, considering the short name of the path and the location in the file.

  • Type: enum
  • Default value: "name"
  • Allowed values: ["name", "location"]

Example

Input
/// Order members alphabetically by name (instead of
/// the default declaration order).
struct widget
{
    /// Refresh the widget.
    void refresh();
    /// Hide the widget.
    void hide();
    /// Show the widget.
    void show();
};
mrdocs.yml
sort-members: true
sort-members-by: name
Preview·sort-members-by

widget

Order members alphabetically by name (instead of the default declaration order).

Synopsis

Declared in <sort‐members‐by.cpp>

struct widget;
Member Functions

Name

Description

hide

Hide the widget.

refresh

Refresh the widget.

show

Show the widget.

widget::hide

Hide the widget.

Synopsis

Declared in <sort‐members‐by.cpp>

void
hide();

widget::refresh

Refresh the widget.

Synopsis

Declared in <sort‐members‐by.cpp>

void
refresh();

widget::show

Show the widget.

Synopsis

Declared in <sort‐members‐by.cpp>

void
show();

sort-namespace-members-by

Determine how members of a namespace are sorted

Although members of namespaces are always sorted, determine how members of a namespace are sorted. When set to name, members are sorted by name. When set to location, members are sorted by their primary location in the source code, considering the short name of the path and the location in the file.

  • Type: enum
  • Default value: "name"
  • Allowed values: ["name", "location"]

Example

Input
namespace lib {

/// Initialize the library.
void init();
/// Connect to a remote service.
void connect();
/// Shut everything down.
void shutdown();

}
mrdocs.yml
sort-members: true
sort-namespace-members-by: name
Preview·sort-namespace-members-by

lib::connect

Connect to a remote service.

Synopsis

Declared in <sort‐namespace‐members‐by.cpp>

void
connect();

lib::init

Initialize the library.

Synopsis

Declared in <sort‐namespace‐members‐by.cpp>

void
init();

lib::shutdown

Shut everything down.

Synopsis

Declared in <sort‐namespace‐members‐by.cpp>

void
shutdown();

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

Example

Input
/// A class whose constructors should head the
/// rendered member list regardless of where the
/// declarations sit in the source.
struct widget
{
    /// Hide the widget.
    void hide();
    /// Show the widget.
    void show();
    /// Construct an empty widget.
    widget();
    /// Construct a widget with the given label.
    widget(const char* label);
};
mrdocs.yml
sort-members: true
sort-members-ctors-1st: true
Preview·sort-members-ctors-1st

widget

A class whose constructors should head the rendered member list regardless of where the declarations sit in the source.

Synopsis

Declared in <sort‐members‐ctors‐1st.cpp>

struct widget;
Member Functions

Name

Description

widget [constructor]

Constructors

hide

Hide the widget.

show

Show the widget.

widget::widget

Constructors

Synopses

Declared in <sort‐members‐ctors‐1st.cpp>

Construct an empty widget.

widget();

» more...

Construct a widget with the given label.

widget(char const* label);

» more...

widget::widget

Construct an empty widget.

Synopsis

Declared in <sort‐members‐ctors‐1st.cpp>

widget();

widget::widget

Construct a widget with the given label.

Synopsis

Declared in <sort‐members‐ctors‐1st.cpp>

widget(char const* label);
Parameters

Name

Description

label

The value to construct from

widget::hide

Hide the widget.

Synopsis

Declared in <sort‐members‐ctors‐1st.cpp>

void
hide();

widget::show

Show the widget.

Synopsis

Declared in <sort‐members‐ctors‐1st.cpp>

void
show();

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

Example

Input
/// A class whose destructor sits at the top of the
/// member list.
struct widget
{
    /// Refresh the widget.
    void refresh();
    /// Construct an empty widget.
    widget();
    /// Destroy the widget and release resources.
    ~widget();
};
mrdocs.yml
sort-members: true
sort-members-dtors-1st: true
Preview·sort-members-dtors-1st

widget

A class whose destructor sits at the top of the member list.

Synopsis

Declared in <sort‐members‐dtors‐1st.cpp>

struct widget;
Member Functions

Name

Description

widget [constructor]

Construct an empty widget.

~widget [destructor]

Destroy the widget and release resources.

refresh

Refresh the widget.

widget::widget

Construct an empty widget.

Synopsis

Declared in <sort‐members‐dtors‐1st.cpp>

widget();

widget::~widget

Destroy the widget and release resources.

Synopsis

Declared in <sort‐members‐dtors‐1st.cpp>

~widget();

widget::refresh

Refresh the widget.

Synopsis

Declared in <sort‐members‐dtors‐1st.cpp>

void
refresh();

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

Example

Input
/// A class whose assignment operators should be
/// grouped at the top of the member list.
struct widget
{
    /// Refresh the widget.
    void refresh();
    /// Copy-assign from another widget.
    widget& operator=(const widget&);
    /// Move-assign from another widget.
    widget& operator=(widget&&);
};
mrdocs.yml
sort-members: true
sort-members-assignment-1st: true
Preview·sort-members-assignment-1st

widget

A class whose assignment operators should be grouped at the top of the member list.

Synopsis

Declared in <sort‐members‐assignment‐1st.cpp>

struct widget;
Member Functions

Name

Description

operator=

Assignment operators

refresh

Refresh the widget.

widget::operator=

Assignment operators

Synopses

Declared in <sort‐members‐assignment‐1st.cpp>

Copy‐assign from another widget.

widget&
operator=(widget const& other);

» more...

Move‐assign from another widget.

widget&
operator=(widget&& other);

» more...

widget::operator=

Copy‐assign from another widget.

Synopsis

Declared in <sort‐members‐assignment‐1st.cpp>

widget&
operator=(widget const& other);
Return Value

Reference to the current object

Parameters

Name

Description

other

The object to copy assign from

widget::operator=

Move‐assign from another widget.

Synopsis

Declared in <sort‐members‐assignment‐1st.cpp>

widget&
operator=(widget&& other);
Return Value

Reference to the current object

Parameters

Name

Description

other

The object to move assign from

widget::refresh

Refresh the widget.

Synopsis

Declared in <sort‐members‐assignment‐1st.cpp>

void
refresh();

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

Example

Input
/// A class whose conversion operators are pushed to
/// the bottom of the member list.
struct value
{
    /// Read the underlying integer.
    int get() const;
    /// Convert to `bool` for use in conditions.
    explicit operator bool() const;
    /// Convert to `int` for arithmetic contexts.
    explicit operator int() const;
};
mrdocs.yml
sort-members: true
sort-members-conversion-last: true
Preview·sort-members-conversion-last

value

A class whose conversion operators are pushed to the bottom of the member list.

Synopsis

Declared in <sort‐members‐conversion‐last.cpp>

struct value;
Member Functions

Name

Description

get

Read the underlying integer.

operator bool

Convert to bool for use in conditions.

operator int

Convert to int for arithmetic contexts.

value::get

Read the underlying integer.

Synopsis

Declared in <sort‐members‐conversion‐last.cpp>

int
get() const;

value::operator bool

Convert to bool for use in conditions.

Synopsis

Declared in <sort‐members‐conversion‐last.cpp>

explicit
operator bool() const;
Return Value

The object converted to bool

value::operator int

Convert to int for arithmetic contexts.

Synopsis

Declared in <sort‐members‐conversion‐last.cpp>

explicit
operator int() const;
Return Value

The object converted to int

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

Example

Input
/// A class whose relational operators sit at the
/// bottom of the member list.
struct value
{
    /// Get the underlying integer.
    int get() const;
    /// Equality comparison.
    bool operator==(const value&) const;
    /// Less-than comparison.
    bool operator<(const value&) const;
};
mrdocs.yml
sort-members: true
sort-members-relational-last: true
Preview·sort-members-relational-last

value

A class whose relational operators sit at the bottom of the member list.

Synopsis

Declared in <sort‐members‐relational‐last.cpp>

struct value;
Member Functions

Name

Description

get

Get the underlying integer.

operator==

Equality comparison.

operator<

Less‐than comparison.

value::get

Get the underlying integer.

Synopsis

Declared in <sort‐members‐relational‐last.cpp>

int
get() const;
Return Value

the underlying integer.

value::operator==

Equality comparison.

Synopsis

Declared in <sort‐members‐relational‐last.cpp>

bool
operator==(value const& rhs) const;
Return Value

true if the objects are equal, false otherwise

Parameters

Name

Description

rhs

The right operand

value::operator<

Less‐than comparison.

Synopsis

Declared in <sort‐members‐relational‐last.cpp>

bool
operator<(value const& rhs) const;
Return Value

true if the left object is less than the right object, false otherwise

Parameters

Name

Description

rhs

The right operand

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

Example

Input
#include <type_traits>

/** Multiply by two, but only for integers.

    The `std::enable_if_t` SFINAE on the return type
    restricts the overload to integral arguments.
*/
template <class T>
std::enable_if_t<std::is_integral_v<T>, T>
twice(T x);
mrdocs.yml
sfinae: true
Preview·sfinae

twice

Multiply by two, but only for integers.

Synopsis

Declared in <sfinae.cpp>

template<class T>
T
twice(T x)
requires std::is_integral_v<T>;
Description

The std::enable_if_t SFINAE on the return type restricts the overload to integral arguments.

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

Example

Input
/** Compute the absolute value of an integer.

    One overload takes `int` and the other `long`,
    so the documentation page lists both side by side.
*/
int abs(int x);

/// @copydoc abs(int)
long abs(long x);
mrdocs.yml
overloads: true
Preview·overloads

abs

Compute the absolute value of an integer.

Synopses

Declared in <overloads.cpp>

Compute the absolute value of an integer.

int
abs(int x);

» more...

Compute the absolute value of an integer.

long
abs(long x);

» more...

abs

Compute the absolute value of an integer.

Synopsis

Declared in <overloads.cpp>

int
abs(int x);
Description

One overload takes int and the other long, so the documentation page lists both side by side.

abs

Compute the absolute value of an integer.

Synopsis

Declared in <overloads.cpp>

long
abs(long x);
Description

One overload takes int and the other long, so the documentation page lists both side by side.

missing-include-prefixes

Include path prefixes allowed to be missing

Specifies path prefixes for include files that, if missing, will not cause documentation generation to fail. Missing files with these prefixes are served as empty files from an in-memory file system, allowing processing to continue. For example, use "llvm/" to forgive all includes from LLVM. If any such path is specified, MrDocs will attempt to synthesize missing included types. Only simple sets of non-conflicting inferred types can be synthesized. For more complex types or for better control, provide a shim using the "missing-include-shims" option.

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

Example

mrdocs.yml
missing-include-prefixes:
  - "llvm/"
  - "boost/"

missing-include-shims

Shims for forgiven missing include files

Specifies a map of include file paths to shim contents. If a missing include file matches a forgiven prefix, MrDocs will use the shim content from this map as the file contents. If no shim is provided for a forgiven file, an empty file is used by default.

  • Type: map
  • Default value: {}

Example

mrdocs.yml
missing-include-shims:
  "llvm/ADT/StringRef.h": |
    namespace llvm { class StringRef; }
  "boost/version.hpp": |
    #define BOOST_VERSION 108400

auto-brief

Use the first line of the comment as the brief

When set to true, Mr.Docs 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

Example

Input
/** Truncate a string to the given length.

    The first sentence of this comment becomes the
    brief; the rest is the description.
*/
void truncate(char* s, int n);
mrdocs.yml
auto-brief: true
Preview·auto-brief

truncate

Truncate a string to the given length.

Synopsis

Declared in <auto‐brief.cpp>

void
truncate(
    char* s,
    int n);
Description

The first sentence of this comment becomes the brief; the rest is the description.

auto-relates

Automatically find non-member functions

When set to true, Mr.Docs automatically finds non-member functions that are related to the current class.

  • Type: boolean
  • Default value: true

Example

Input
/** A two-dimensional point.
*/
struct point
{
    double x;
    double y;
};

/** Print a point to stdout.

    The free function takes `point` as its only
    parameter, so it gets attached to `point` as a
    related function.
*/
void print(point p);
mrdocs.yml
auto-relates: true
Preview·auto-relates

point

A two‐dimensional point.

Synopsis

Declared in <auto‐relates.cpp>

struct point;
Data Members

Name

x

y
Non-Member Functions

Name

Description

print

Print a point to stdout.

point::x

Synopsis

Declared in <auto‐relates.cpp>

double x;

point::y

Synopsis

Declared in <auto‐relates.cpp>

double y;

print

Print a point to stdout.

Synopsis

Declared in <auto‐relates.cpp>

void
print(point p);
Description

The free function takes point as its only parameter, so it gets attached to point as a related function.

Parameters

Name

Description

p

A two‐dimensional point.

auto-function-metadata

Automatically provide missing documentation for special functions and trivial metadata

When set to true, Mr.Docs automatically provides documentation for special functions, such as constructors, destructors, and operators. It also provides documentation for missing documentation metadata, such as known types.

  • Type: boolean
  • Default value: true

Example

Input
/// A 2D vector.
struct vec2
{
    /// Construct from `x` and `y` components.
    vec2(double x, double y);

    vec2(vec2 const&);
    vec2(vec2&&) noexcept;
    ~vec2();

    vec2& operator=(vec2 const&);

    bool operator==(vec2 const&) const;

    /// Returns the Euclidean length of the vector.
    double magnitude() const;

    /// Translate this vector by `delta`.
    vec2 translated(vec2 const& delta) const;
};
mrdocs.yml
auto-function-metadata: true
Preview·auto-function-metadata

vec2

A 2D vector.

Synopsis

Declared in <auto‐function‐metadata.cpp>

struct vec2;
Member Functions

Name

Description

vec2 [constructor]

Construct from x and y components.

~vec2 [destructor]

Destructor

operator=

Copy assignment operator

magnitude

Returns the Euclidean length of the vector.

translated

Translate this vector by delta.

operator==

Equality operator

vec2::vec2

Construct from x and y components.

Synopses

Declared in <auto‐function‐metadata.cpp>

Copy constructor

vec2(vec2 const& other);

» more...

Move constructor

vec2(vec2&& other) noexcept;

» more...

Construct from x and y components.

vec2(
    double x,
    double y);

» more...

vec2::vec2

Copy constructor

Synopsis

Declared in <auto‐function‐metadata.cpp>

vec2(vec2 const& other);
Parameters

Name

Description

other

The object to copy construct from

vec2::vec2

Move constructor

Synopsis

Declared in <auto‐function‐metadata.cpp>

vec2(vec2&& other) noexcept;
Parameters

Name

Description

other

The object to move construct from

vec2::vec2

Construct from x and y components.

Synopsis

Declared in <auto‐function‐metadata.cpp>

vec2(
    double x,
    double y);
Parameters

Name

Description

x

The value to construct from

vec2::~vec2

Destructor

Synopsis

Declared in <auto‐function‐metadata.cpp>

~vec2();

vec2::operator=

Copy assignment operator

Synopsis

Declared in <auto‐function‐metadata.cpp>

vec2&
operator=(vec2 const& other);
Return Value

Reference to the current object

Parameters

Name

Description

other

The object to copy assign from

vec2::magnitude

Returns the Euclidean length of the vector.

Synopsis

Declared in <auto‐function‐metadata.cpp>

double
magnitude() const;
Return Value

the Euclidean length of the vector.

vec2::translated

Translate this vector by delta.

Synopsis

Declared in <auto‐function‐metadata.cpp>

vec2
translated(vec2 const& delta) const;
Return Value

A 2D vector.

Parameters

Name

Description

delta

A 2D vector.

vec2::operator==

Equality operator

Synopsis

Declared in <auto‐function‐metadata.cpp>

bool
operator==(vec2 const& rhs) const;
Return Value

true if the objects are equal, false otherwise

Parameters

Name

Description

rhs

The right operand

Output

Generators to create the documentation and their options

Name Description Default
output
(path) 		Directory or file for generating output "<config-dir>/reference-output"
generator
(string) 		Generator used to create the documentation "html"
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"
addons-supplemental
(list of paths) 		Additional addons layered on top of the base 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
show-enum-constants
(boolean) 		Show enum constant pages in the documentation false
global-namespace-index
(boolean) 		Use the global namespace page as an index for all symbols true
stylesheets
(list of strings) 		Ordered list of stylesheets to apply to HTML output []
no-default-styles
(boolean) 		Disable the bundled default stylesheet false
stylesdir
(string) 		Directory for linked stylesheets "css"
linkcss
(boolean) 		Link stylesheets instead of embedding them false
copycss
(boolean) 		Copy local stylesheets when linking true

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"

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 built-in generators include adoc, html, and xml; data-driven generators can be added by dropping a template folder under <addon>/generator/<name>/.

  • Type: string
  • Default value: "html"

Example

Input
/// Multiply two integers.
int multiply(int a, int b);
mrdocs.yml
generator: adoc
Preview·generator

multiply

Multiply two integers.

Synopsis

Declared in <generator.cpp>

int
multiply(
    int a,
    int b);

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

Example

mrdocs.yml
multipage: true

base-url

Base URL for links to source code

The prefix for links to the source code. MrDocs joins it with the path of each source file to build the link.

  • Type: string
  • Default value:

Example

Input
/** Compute the area of a circle of radius `r`. */
double area(double r);
mrdocs.yml
base-url: https://github.com/example/geom/blob/main/
Preview·base-url

area

Compute the area of a circle of radius r.

Synopsis

Declared in <base‐url.cpp>

double
area(double r);

addons

Path to the Addons directory

The directory of template files the generators use to build the documentation. Leave it unset to use the defaults that ship at share/mrdocs/addons in the MrDocs installation. To customize the output, copy those defaults to your own directory and point this option at it.

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

addons-supplemental

Additional addons layered on top of the base addons

Optional list of supplemental addons directories that are loaded after the base addons (built-in or replacement). Files in later supplemental directories override files from earlier ones and from the base addons. Use this to add or override a few templates/helpers without copying the entire addons tree.

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

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

Example

mrdocs.yml
multipage: true
legible-names: 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

Example

Input
/// A tiny example library.
///
/// Holds the entry points the documentation calls out
/// and a few helpers consumed by the rest of the project.
namespace lib {

/// A function inside `lib`. With `show-namespaces: true`
/// the namespace appears in the rendered output as a
/// dedicated entry; with `false` the namespace is
/// flattened into the parent.
void run();

}
mrdocs.yml
show-namespaces: true
Preview·show-namespaces

Global namespace

Namespaces

Name

Description

lib

A tiny example library.

lib

A tiny example library.

Description

Holds the entry points the documentation calls out and a few helpers consumed by the rest of the project.

Functions

Name

Description

run

A function inside lib. With show‐namespaces: true the namespace appears in the rendered output as a dedicated entry; with false the namespace is flattened into the parent.

lib::run

A function inside lib. With show‐namespaces: true the namespace appears in the rendered output as a dedicated entry; with false the namespace is flattened into the parent.

Synopsis

Declared in <show‐namespaces.cpp>

void
run();

show-enum-constants

Show enum constant pages in the documentation

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

  • Type: boolean
  • Default value: false

Example

Input
/// Status of a network operation.
enum class status
{
    /// Operation succeeded.
    ok,
    /// Operation timed out.
    timeout,
    /// Operation failed for another reason.
    error,
};
mrdocs.yml
show-enum-constants: true
Preview·show-enum-constants

status

Status of a network operation.

Synopsis

Declared in <show‐enum‐constants.cpp>

enum class status : int;
Members

Name

Description

ok

Operation succeeded.

timeout

Operation timed out.

error

Operation failed for another reason.

status::ok

Operation succeeded.

Synopsis

Declared in <show‐enum‐constants.cpp>

ok

status::timeout

Operation timed out.

Synopsis

Declared in <show‐enum‐constants.cpp>

timeout

status::error

Operation failed for another reason.

Synopsis

Declared in <show‐enum‐constants.cpp>

error

global-namespace-index

Use the global namespace page as an index for all symbols

When set to true, the page for the global namespace will recursively list all symbols in the documentation, not just those in the global namespace. This makes the global namespace page act as an index for the entire project.

  • Type: boolean
  • Default value: true

stylesheets

Ordered list of stylesheets to apply to HTML output

Ordered list of stylesheet names or paths. If empty, the bundled stylesheet is used. Entries can be local paths or remote URLs; remote URLs are only linked when linkcss is true. Inline mode embeds local styles; link mode emits <link> tags for each entry and copies local files.

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

no-default-styles

Disable the bundled default stylesheet

When set to true, the bundled stylesheet is not applied. Combine with an empty stylesheets list to emit no styles at all.

  • Type: boolean
  • Default value: false

stylesdir

Directory for linked stylesheets

The directory MrDocs writes into the href of linked stylesheets when linkcss is true. Defaults to css. When local styles are copied, the directory is created under the output root, for example css/mrdocs-default.css.

  • Type: string
  • Default value: "css"

linkcss

Link stylesheets instead of embedding them

When set to true, stylesheets are linked with <link> tags instead of being inlined. Links use stylesdir plus the stylesheet name (e.g. css/custom.css). Local styles are copied unless copycss is false; remote URLs are linked as-is.

  • Type: boolean
  • Default value: false

copycss

Copy local stylesheets when linking

When linkcss is true, copy bundled and local stylesheet files into the output under stylesdir. Remote URLs are not copied. Set to false to skip copying.

  • Type: boolean
  • Default value: true

Diagnostics

Warnings, logging, and error handling

These options control the diagnostics Mr.Docs emits as it runs: the warnings it reports about undocumented or malformed documentation, the logging verbosity and report file, the concurrency it uses, and how it behaves when it encounters errors.

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
error-on-empty-corpus
(boolean) 		Treat an empty corpus as an error true
concurrency
(unsigned integer) 		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

verbose

Verbose output

When set to true, MrDocs prints extra information as it generates 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

error-on-empty-corpus

Treat an empty corpus as an error

When set to true, MrDocs treats an empty corpus as a hard error and exits with a failure status instead of emitting a warning and succeeding. A corpus counts as empty when no symbols are extracted; because the global namespace is always present in the model, a corpus that contains only the global namespace and no other declaration is also treated as empty. This usually means nothing was extracted, which is rarely intended in CI, so this turns that silent success into a detectable failure. This escalation applies regardless of the warn-as-error option.

  • Type: boolean
  • Default value: true

concurrency

Number of threads to use

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

  • Type: unsigned integer
  • 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