Maintain Mono API Documentation Safely with monodocer

monodocer turns a .NET assembly into ECMA-style XML documentation stubs, ready for you to fill in and package for MonoDoc. Allow 15 to 30 minutes for a first run. The examples use the installed monodoc-base package, version 6.8.0.105+dfsg-3.6ubuntu2. Its command reports itself as mdoc 5.7.4.9; the local manual says that monodocer is obsolete and that mdoc update is its replacement.

You need a readable assembly and a writable documentation directory. These commands only write under the directory passed to -path or -updateto. They do not require root. Keep the assembly and your source XML under version control before making updates.

1. Choose an assembly and an empty output directory

Use a file path for the assembly, or the name of an assembly in the Global Assembly Cache. This example uses an installed reference assembly and a new directory under your home directory:

$ assembly=/usr/lib/mono/4.8-api/Mono.Posix.dll
$ output="$HOME/monodoc/Mono.Posix"
$ test -r "$assembly" && echo "assembly is readable"
assembly is readable
$ mkdir -p "$output"

The output directory should be separate from the assembly. Do not point -path at your source tree unless that is deliberately how your project is organised. A run creates index.xml plus namespace and type XML files, so an accidental path is easy to fill with generated files.

Checkpoint: Check the two values before continuing. printf '%s\n' "$assembly" "$output" should show the assembly you intend to document and a writable destination.

2. Generate the initial documentation stubs

Run monodocer with the assembly and output path. The -name value becomes the title in index.xml. -pretty makes the XML easier to review:

$ monodocer -assembly:"$assembly" -path:"$output" \
    -name:'Mono.Posix example' -pretty
mdoc 5.7.4.9
Updating Mono.Posix, Version=4.0.0.0, Culture=neutral, PublicKeyToken=0738eb9f132ed756 from /usr/lib/mono/4.8-api/Mono.Posix.dll
New Type: Mono.Posix.AccessMode
Member Added: F_OK

The exact list of types and members depends on the assembly. A successful exit status is useful, but also inspect the files:

$ test -s "$output/index.xml" && echo 'index created'
index created
$ find "$output" -maxdepth 2 -type f -name '*.xml' | head
/home/you/monodoc/Mono.Posix/index.xml
/home/you/monodoc/Mono.Posix/Mono.Posix/AccessMode.xml

New documentation contains To be added. markers under Docs. Those are the places for summaries, remarks, parameters and examples. Treat structural data such as full type names, member signatures, interfaces and parameter lists as generated metadata. Editing it by hand can make later updates unreliable.

3. Add prose without changing generated identity

Open a generated type file and replace the relevant To be added. text in its documentation elements. Preserve the surrounding XML. For example, a summary is ordinary XML text inside the existing Docs element:

<summary>Provides access to Unix file metadata.</summary>
<remarks>
  <para>The values describe the file at the time the object reads it.</para>
</remarks>

Use the ECMA string IDs when linking to another API member. A type uses T:, a method uses M:, a property uses P:, a field uses F:, and an event uses E:. Constructors use .ctor. Generic types carry their arity, such as T:System.Collections.Generic.List\`1. The backtick is part of the identifier.

Do not put arbitrary prose directly where the format expects XML-only content. Use the elements described by the manual, such as para, see, paramref, example and code. Keep a small commit after this editing pass so the generated baseline and the human-written documentation can be recovered independently.

4. Update after an API change

Run the same assembly update against a copy first. The default behaviour adds new types and members and updates the generated inventory, while leaving documentation text for existing members in place:

$ review="$HOME/monodoc/Mono.Posix-review"
$ cp -a "$output" "$review"
$ monodocer -assembly:"$assembly" -path:"$review" -pretty
$ git -C "$HOME/monodoc" diff --stat -- Mono.Posix-review

If you need to update one namespace or type, use -namespace:NAMESPACE or -type:TYPE. -ignoremembers updates types without adding or removing members. These filters narrow the update; they are not a substitute for reviewing the resulting diff.

Warning: Do not add -delete casually. It permits removal of documentation for members no longer present in the assembly. If a whole type disappeared, the manual says its file is renamed with a .remove extension rather than deleted. Keep the pre-update copy until the diff and API change are understood. Recovery is to restore the directory from version control or copy the untouched backup over the review directory.

5. Package the documentation

Once the XML has passed review, build the distributable archive and tree. On this installation the compatibility command is available:

$ mdassembler --ecma "$output" -out:"$HOME/monodoc/Mono.Posix"
$ ls -lh "$HOME/monodoc/Mono.Posix.tree" "$HOME/monodoc/Mono.Posix.zip"
-rw-r--r-- 1 you you ... Mono.Posix.tree
-rw-r--r-- 1 you you ... Mono.Posix.zip

The equivalent modern front end is mdoc assemble -o PREFIX DIRECTORY. The local manual describes a separate .sources file, whose provider is ecma, whose basefile matches the archive prefix, and whose path selects where the documentation appears in the browser. Create and review that file as part of your package rather than copying files straight into a system directory.

Installation into the directory returned by pkg-config monodoc --variable sourcesdir changes system-wide documentation and normally needs elevated privileges. Do that only as a separate deployment step, after testing the archive. There is no undo command for a blind copy; retain the previous archive and source registration so you can restore them deliberately.

6. Prefer mdoc for new automation

The installed monodocer entry is a compatibility interface. Its -V output is the same mdoc 5.7.4.9 banner, and its help points at the newer command family. For a new script, use the documented equivalent:

$ mdoc update -o "$output" "$assembly"
mdoc 5.7.4.9

Keep monodocer in an existing workflow when compatibility matters, but record the installed package version and test updates against a copy. The XML format and the safety boundaries matter more than the command name.

Done means