Small slide deck explaining how to use MonoDoc.

1. Mono Documentation Pipeline

2. MONODOC ENGINE

3. 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

4. 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”

5. 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

6. DOCUMENTATION PIPELINE

7. 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

8. 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.

9. 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.

10. 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

11. More Information
• Generating Docs:
– http://www.mono-project.com/Generating_Documentation
• ECMA XML markup:
– http://www.mono-project.com/Monodoc_Editing

12. 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

13. 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.