Update MonoDoc XML Safely with mdoc update

You will finish with a directory of MonoDoc XML files generated from a .NET assembly, or with an existing documentation directory updated to match a newer assembly. The examples use the mdoc installed by Ubuntu's monodoc-base package, version 6.8.0.105+dfsg-3.6ubuntu2, which reports itself as mdoc 5.7.4.9.

Before you start

Have an assembly file you are allowed to inspect, a writable output directory, and any dependent assemblies needed to load it. Allow about five minutes for a small library. Large framework assemblies can produce many XML files and take longer.

mdoc update reads metadata from the assembly. It does not normally read documentation comments embedded in source code. Use --import when you also need to bring in XML produced by a C# compiler or ECMA-335 documentation.

$ 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

1. Create documentation stubs in a new directory

Use -o to choose the documentation root and pass the assembly as the final argument. The directory is both the destination for a first run and the source directory on later updates. Use a new, empty directory first so you can inspect the result without mixing it with an older documentation set.

$ mkdir -p /path/to/monodoc-xml
$ mdoc update -o /path/to/monodoc-xml /path/to/Example.Library.dll
mdoc 5.7.4.9
Updating Example.Library, Version=1.0.0.0, Culture=neutral, PublicKeyToken=null from /path/to/Example.Library.dll

The exact progress lines depend on the assembly. You should see messages for new types and members, followed by XML files below the output directory. Check the files without opening them in an editor that might rewrite their encoding:

$ find /path/to/monodoc-xml -type f -name '*.xml' -print | sort
$ xmllint --noout /path/to/monodoc-xml/ns-Example.Library.xml

The command creates stubs, not polished prose. Review the XML and complete the descriptions before publishing it.

2. Update an existing documentation set

Run the same command against the new assembly and the existing documentation root. Existing documentation is preserved while newly found types and members receive stubs. If the tool can identify a rename, it may carry documentation across that change.

$ mdoc update -o /path/to/monodoc-xml /path/to/Example.Library-2.0.dll

Use version metadata when you need to record when new API appeared:

$ mdoc update --since=2.0 -o /path/to/monodoc-xml /path/to/Example.Library-2.0.dll

That adds a <since version="2.0"/> element for types and members that were not present in the previous assembly version. Choose the value deliberately; it is documentation data, not a check against a package manager.

$ git -C /path/to/documentation diff --stat
$ git -C /path/to/documentation diff -- '*.xml'

If the XML is under version control, recovery is straightforward: discard only the reviewed update from your branch or restore the affected files from the last commit. Do not use a destructive delete command on the whole documentation root.

3. Make dependency resolution explicit

If the target assembly refers to libraries that should not themselves be documented, add their directory with -L. This is a search path, not an instruction to generate documentation for every assembly found there.

$ mdoc update -L /path/to/dependencies \
    -o /path/to/monodoc-xml /path/to/Example.Library.dll

For one dependency, -r takes the dependency assembly and searches the directory containing it. It is equivalent to adding that directory with -L.

$ mdoc update -r=/path/to/dependencies/Support.Library.dll \
    -o /path/to/monodoc-xml /path/to/Example.Library.dll

In this version, -L normally searches its directory recursively. Add --disable-searchdir-recurse if that broad search is undesirable. A common failure is pointing at a source tree or a directory containing incompatible builds, which can make type resolution ambiguous.

4. Import compiler documentation when needed

Use -i or --import for an XML documentation file. The file may be compiler output from csc /doc or ECMA-335 XML. This supplements the assembly-driven update; it does not replace the assembly argument.

$ mdoc update --import=/path/to/Example.Library.xml \
    -o /path/to/monodoc-xml /path/to/Example.Library.dll

Keep the import file matched to the assembly version you are processing. Importing comments from a different build can leave useful-looking text attached to the wrong API.

5. Limit or preserve the update

For a focused review, use --type with the type to update:

$ mdoc update --type=Example.Library.Widget \
    -o /path/to/monodoc-xml /path/to/Example.Library.dll

Do not use --delete casually. It allows members absent from the current assembly to be removed from the XML. If a type has disappeared, its documentation file is renamed with a .remove extension instead. Version tracking uses //AssemblyVersion elements, so deletion is safest when those elements exist and the assembly history is understood.

When removal is not wanted, --preserve keeps missing members marked as preserved instead of deleting them. Treat this as a review aid, not proof that the members still exist at runtime.

6. Verify the result

Check that XML is well formed and that the expected namespace files exist. For a narrow run, confirm the target type appears in the generated files. Then review additions, renames, .remove files, and any assembly version or since metadata before committing.

$ find /path/to/monodoc-xml -type f -name '*.xml' -print | sort
$ xmllint --noout $(find /path/to/monodoc-xml -type f -name '*.xml' -print)
$ rg -n 'Example\.Library\.Widget|since version="2\.0"' /path/to/monodoc-xml

mdoc update does not require elevated privileges when the assembly and output are yours. Use sudo only if the final documentation directory is deliberately owned by root, and generate into a user-writable staging directory first. That makes failed updates easy to inspect and avoids giving a documentation parser unnecessary system-wide write access.

Done means

• The installed mdoc version and package are known.
• The output directory contains well-formed XML for the intended assembly.
• Dependencies were supplied with -L or -r only where needed.
• Imported comments match the assembly being processed.
• Any --delete, --preserve, or version flag was chosen deliberately.
• The XML diff has been reviewed before it is committed or installed.