Home
RSS SyndicationWhat is mdoc? - Jonathan Pryor's web log
« Re-Introducing mdoc | Main | TekPub's Mastering LINQ Challenge »
What is mdoc?
mdoc is an assembly-based documentation management system, which recently added support for .NET .
I say "assembly based" because an alternative is source-based, which is what "normal" C# XML documentation, JavaDoc, and perlpod provide. Unlike these source-based systems, in mdoc documentation for public types and members are not present within source code. Instead, documentation is stored externally (to the source), in a directory of XML files (hereafter refered to as the mdoc repository).
Furthermore, mdoc provides commands to:
- synchronize the mdoc repository with an assembly being documented (adding to the repository any types and members added to the assembly);
- to export the mdoc repository into HTML or Microsoft's XML format (for use with an IDE like Visual Studio and MonoDevelop);
- to validate the mdoc repository XML schema;
- to assemble the mdoc repository for use with the Monodoc Documentation Browser and the ASP.NET front-end.
Why the mdoc repository?
Why have a directory of XML files as the mdoc repository? The mdoc repository comes from the need to satisfy two goals:
- The compiler-generated /doc XML contains no type information.
- Having types is very useful for HTML output/etc., so the type information must come from somewhere.
Said "somewhere" could be the actual assemblies being documented, but this has other downsides (e.g. it would complicate supporting different versions of the same assembly). mdoc uses the repository to contain both documentation and full type information, so that the source assemblies are only needed to update the repository (and nothing else).
Why use mdoc?
Which provides enough background to get to the point: why use mdoc?
You would primarily want to use mdoc if you want to view your documentation outside of an IDE, e.g. within a web browser or stand-alone documentation browser. Most mdoc functionality is geared toward making documentation viewable (e.g. mdoc export-html and mdoc assemble), and making the documentation that is viewed more useful (such as the full type information provided by mdoc update and the generation of <exception/> elements for documentation provided by mdoc update --exceptions).
Next time, we'll discuss how to use mdoc.
blog comments powered by Disqus