Diagnostics

These options govern what MrDocs reports while it runs and how it behaves when something goes wrong. They change what appears in your terminal, not the documentation itself, so there is no rendered example below. The Diagnostics reference has the full option list.

Doc-comment lint

The warn-* family treats common documentation problems as warnings, so a CI run can catch them the same way it catches compiler warnings. The most useful ones in practice:

warn-if-undocumented flags exported symbols that have no doc comment.
warn-if-doc-error flags malformed doc comments (broken @param syntax, unterminated code blocks, and similar).
warn-no-paramdoc and warn-unnamed-param flag functions whose parameters are not documented or not named.
warn-if-undoc-enum-val flags enumerators without doc comments.
warn-broken-ref flags @ref and @see targets that do not resolve.

warn-as-error turns every warning into a failure, the usual CI setup once a project is past the bring-up phase.

warnings: true
warn-if-undocumented: true
warn-if-doc-error: true
warn-broken-ref: true
warn-as-error: false

warn-as-error is also a useful local-development tool: turn it on with the warn-if-undocumented family and run MrDocs in a loop while you fill in the missing comments. Each run terminates at the first undocumented symbol, so you can knock them out one by one until the build goes green.

warnings is the master switch: set it to false to silence the entire family at once.

Log verbosity

log-level picks the verbosity (error, warn, info, debug, trace). verbose is the boolean shorthand for the most detailed level.

log-level: info
verbose: false

Runtime tuning

concurrency caps the number of threads MrDocs uses to extract symbols. The default 0 matches the hardware; lower it on shared CI runners or to make logs easier to read.

concurrency: 4