Mono Documentation Pipeline
MONODOC ENGINE
MonoDoc Engine• Provides documentation for a given member  – Use C# ECMA type reference syntax, ex:  – T:System.String  – ...
MonoDoc Data Sources• At runtime MonoDoc uses compiled docs  – For the library “MyLibrary” it has:  – Hierarchy data: MyLi...
MonoDoc Front-ends• Multiple front-ends built on top of the engine• Native clients   – MacDoc on OSX   – MonoDoc on Gtk# f...
DOCUMENTATION PIPELINE
CLI ECMA XML Documents• We use the ECMA CLI XML format to doc• The “mdoc” tool can:  – Compile the ECMA XML docs into .tre...
ECMA XML• Use ECMA XML to document your code• Generate stubs and document them• Our tools will update your docs as your AP...
ECMA XML Maintenance Basics• Build your library:   – csc /target:library Demo.dll• Generate stubs:   – mdoc update --delet...
Publish Your Docs• Assemble your XML files into a tree/zip file:  – mdoc assemble -o Demo DemoDocs  – The above generates ...
More Information• Generating Docs:  – http://www.mono-project.com/Generating_Documentation• ECMA XML markup:  – http://www...
C# inline docs• They are typically poor  – Best case scenario, they document <summary>  – Often not enough  – Lack samples...
FAQ• Should I maintain my docs in C# /// comments?   – Avoid if you can. Go full external ECMA XML• Are there redeeming qu...
Upcoming SlideShare
Loading in …5
×

Using monodoc

1,958 views

Published on

Small slide deck explaining how to use MonoDoc.

Published in: Technology
  • Be the first to comment

  • Be the first to like this

Using monodoc

  1. 1. Mono Documentation Pipeline
  2. 2. MONODOC ENGINE
  3. 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. 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. 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. 6. DOCUMENTATION PIPELINE
  7. 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. 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. 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. 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. 11. More Information• Generating Docs: – http://www.mono-project.com/Generating_Documentation• ECMA XML markup: – http://www.mono-project.com/Monodoc_Editing
  12. 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. 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.

×