• Full Name Full Name Comment goes here.
    Are you sure you want to
    Your message goes here
    Be the first to comment
    Be the first to like this
No Downloads

Views

Total Views
1,147
On Slideshare
0
From Embeds
0
Number of Embeds
0

Actions

Shares
Downloads
2
Comments
0
Likes
0

Embeds 0

No embeds

Report content

Flagged as inappropriate Flag as inappropriate
Flag as inappropriate

Select your reason for flagging this presentation as inappropriate.

Cancel
    No notes for slide

Transcript

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