Validate Mono ECMA Documentation with mdoc

Run mdoc validate against a Mono documentation tree to catch a schema problem before it reaches a reader. Then learn to tell that apart from an ordinary path or permissions mistake, using mdoc 5.7.4.9 from Debian package monodoc-base 6.8.0.105+dfsg-3.6ubuntu2.

Allow about fifteen minutes. You need a shell, a readable documentation directory produced by mdoc-update, and permission to read its XML files. Validation is read-only: it does not rewrite documentation, load an assembly, install a schema or repair invalid files. No command in this guide needs sudo unless your own documentation directory is deliberately restricted.

1. Confirm the installed command

Start with the executable and package version. These are ordinary read-only checks:

$ command -v mdoc
/usr/bin/mdoc
$ mdoc --version
mdoc 5.7.4.9
$ dpkg-query -W -f='${Package} ${Version}\n' monodoc-base
monodoc-base 6.8.0.105+dfsg-3.6ubuntu2

The wrapper command is mdoc; the package also installs mdoc-validate. Use the wrapper form shown by the manual, mdoc validate, so the selected subcommand and format stay visible in a script or review.

Checkpoint: ask this exact binary for its options before copying an example into automation:

$ mdoc validate --help
usage: mdoc validate [OPTIONS]+ PATHS

Validate PATHS against the specified format schema.

On this installation the help also shows the short -f spelling for --format. The manual documents --format=FORMAT, with ecma as the supported format and the default. Keep --format=ecma in a shared script when being explicit is more useful than relying on that default.

2. Identify the directory to validate

mdoc validate expects one or more paths. For an ECMA documentation set, pass the directory containing files such as index.xml, ns-*.xml and namespace/type XML files. It walks the documentation beneath the path, so a directory is normally the useful boundary:

$ DOCS_DIR=/path/to/ecma/docs
$ test -d "$DOCS_DIR" && test -r "$DOCS_DIR" && echo "directory is readable"
directory is readable
$ find "$DOCS_DIR" -maxdepth 2 -type f \( -name 'index.xml' -o -name 'ns-*.xml' \) -print | sed -n '1,12p'

Replace /path/to/ecma/docs with your real output directory. Do not point the command at a single source-code file or an unrelated XML export and assume the result describes the whole documentation set. The ECMA format has a recognisable layout, and the validator checks paths recursively from wherever you point it.

Warning: if the directory is owned by another account, ask its owner to grant the least read access needed first. Adding sudo can hide an ordinary deployment permission mistake and can make later automation work only when run as root. On the installed 5.7.4.9 binary, a missing path can produce no diagnostic and a zero status, so the separate directory and file checks above are part of validation, not optional decoration.

3. Run the recursive validation

Run the documented default format first:

$ mdoc validate "$DOCS_DIR"
$ printf 'validator exit status: %s\n' "$?"
validator exit status: 0

Checkpoint: a status of zero is what you want. The validator normally stays quiet when the supplied ECMA tree passes. Run the second command immediately afterwards, because $? is replaced by every command you run.

For a script or a review where the format should be obvious, use the equivalent explicit form:

$ mdoc validate --format=ecma "$DOCS_DIR"
$ printf 'validator exit status: %s\n' "$?"
validator exit status: 0

Do not treat a quiet terminal as proof of success if a wrapper swallowed the exit status. Capture the status directly, or use a shell conditional:

$ if mdoc validate --format=ecma "$DOCS_DIR"; then
>     echo 'ECMA documentation is valid'
> else
>     echo 'ECMA documentation failed validation' >&2
>     exit 1
> fi
ECMA documentation is valid

4. Understand what the check covers

The ECMA schema applies to output generated by mdoc-update. The manpage calls out index.xml, ns-*.xml and NamespaceName/TypeName.xml files. This is a format check, not a completeness audit: a valid tree can still contain placeholder documentation, an incomplete assembly surface or text that needs editorial review.

The command also does not regenerate files. If you edited an XML file, validation reads the current tree and reports whether it conforms. If you need new stubs or updated members, use the appropriate mdoc-update workflow separately, then rerun validation against the resulting directory.

Checkpoint: keep the input tree available while you interpret the result. A successful validation changes nothing, so there is no rollback step for this guide.

5. Diagnose a non-zero result

First preserve the failing command and status instead of immediately changing files. A genuine schema problem normally produces a non-zero status and a diagnostic, but the exact text varies with the XML file and installed release. Read the named path, line and schema complaint as the primary clue.

Check the path independently before interpreting a quiet result: this catches the installed command's permissive handling of a missing or empty location.

$ test -d "$DOCS_DIR" || echo 'missing documentation directory'
$ find "$DOCS_DIR" -type f -name '*.xml' -readable | wc -l
$ find "$DOCS_DIR" -type f -name '*.xml' | sed -n '1,12p'

If the directory is missing or unreadable, fix the path or its intended permissions and rerun. If the path is readable but the validator names an XML file, make a small, reviewed correction in the source tree or regenerate that output using your normal documentation process. Do not mass-replace XML with a broad search-and-replace: a change that silences one complaint can invalidate references elsewhere.

After a correction, rerun the full directory command, not only the file that was mentioned. The schema can find more than one fault, and the manual describes the input as a set of related files rather than isolated documents.

6. Keep validation safe in automation

Use a quoted variable and fail the job on a non-zero status:

#!/bin/sh
set -eu
DOCS_DIR=/path/to/ecma/docs
mdoc validate --format=ecma "$DOCS_DIR"
echo 'ECMA documentation passed validation'

This script reads the directory and stops before printing the success message if validation fails. It does not need elevated privileges. If a CI account cannot read the tree, fix the build artefact ownership or permissions in the build process rather than running the validator as root.

Warning: do not put cleanup commands after a failed validation unless you have separately decided they are safe. Removing the XML tree is destructive and cannot be undone by mdoc validate. Preserve the failing artefact when you need to investigate a reproducible schema error.

Done means