MonoDoc Engine• Provides documentation for a given member – Use C# ECMA type reference syntax, ex: – T:System.String – M:System.Int32.ToString () – P:System.Int32.MaxValue – E:System.Foo.MyEvent• Full text body search, or book-like Index search
MonoDoc Data Sources• At runtime MonoDoc uses compiled docs – For the library “MyLibrary” it has: – Hierarchy data: MyLibrary.tree – Actual docs: MyLibrary.zip• Installed in the Mono prefix directory• On Mac also in “External/monodoc”
MonoDoc Front-ends• Multiple front-ends built on top of the engine• Native clients – MacDoc on OSX – MonoDoc on Gtk# for Linux and Windows• Web Client – Webclient• MonoDevelop – Uses it to provide documentation during code completion
CLI ECMA XML Documents• We use the ECMA CLI XML format to doc• The “mdoc” tool can: – Compile the ECMA XML docs into .tree/.zip – Export csc/doc out to ECMA XML – Update existing XML docs to reflect changes in API – Export ECMA XML to VS’s Intellisense XML
ECMA XML• Use ECMA XML to document your code• Generate stubs and document them• Our tools will update your docs as your API evolves, without destroying existing docs. – Designed to maintain the docs long-term.
ECMA XML Maintenance Basics• Build your library: – csc /target:library Demo.dll• Generate stubs: – mdoc update --delete -o DemoDocs Demo.dll• Edit at will – All places that say “To be added.”• Maintain, repeat as many times as needed: – Upgrade your C# code, develop – Re-run mdoc update command.
Publish Your Docs• Assemble your XML files into a tree/zip file: – mdoc assemble -o Demo DemoDocs – The above generates Demo.zip and Demo.tree• Distribute .zip and .tree file• Create “Demo.source” with metadata – Used to specify where docs show up in hierarchy
More Information• Generating Docs: – http://www.mono-project.com/Generating_Documentation• ECMA XML markup: – http://www.mono-project.com/Monodoc_Editing
C# inline docs• They are typically poor – Best case scenario, they document <summary> – Often not enough – Lack samples, remarks others – If you are starting to document, avoid it.• We can export/merge those into ECMA XML – Useful when master docs are in source
FAQ• Should I maintain my docs in C# /// comments? – Avoid if you can. Go full external ECMA XML• Are there redeeming qualites about C# ///? – None, more trouble than they are worth.