http://blogs.clariusconsulting.net/kzu

Daniel Cazzulino's Blog

Go Back to
kzu′s Latest post

NuDoc: A .NET XML API Documentation Reader

A couple days ago I was toying with the idea of generating a static API documentation site in markdown ready for hosting in GitHub. The idea is to make it part of the project wiki, so that anyone can very easily improve the code documentation, and later on somehow allow project authors/contributors to merge back the edited markdown as XML documentation in the code itself, so that the cycle is closed.

So I set out to spike the idea, and the first thing I encountered was that reading XML documentation was something that you either had to do by just using XML APIs in .NET, or you had to use some big piece of software that not only reads documentation but it also can generate an entire site already, in multiple formats with plugins and formatters and what-not. There was no middle ground.

So, instead of building my XML doc <-> markdown wiki synchronizer, I first had to build a simple XML documentation reading  API :) . Straight from the NuDoc site:

Icon NuDoc: A .NET XML API Documentation Reader

A standalone API to read .NET XML documentation files and optionally augment it with reflection information.

NuDoc provides a simple and intuitive API that reads .NET XML documentation files into an in-memory model that can be easily used to generate alternative representations or arbitrary processing. If the read operation is performed using a .NET assembly rather than an XML file, NuDoc will automatically add the reflection information to the in-memory model for the documentation elements, making it very easy to post-process them by grouping by type, namespace, etc.

NuDoc leverages two well-known patterns: the Visitor pattern and the Composite pattern. Essentially, every member in the documentation file is represented as a separate “visitable” type. By simply writing a NuDoc Visitor-derived class, you can process only the elements you’re interested in.

NuDoc can read documentation files from any CIL assembly, and the source tree has explicit unit tests that do so for all major .NET platforms: .NET, WinRT/Metro, Windows Phone and Silverlight.

How to Install

NuDoc is a single assembly with no external dependencies whatsoever and is distributed as a NuGet package. It can be installed issuing the following command in the Package Manager Console:

PM> Install-Package NuDoc

Sample code

This is a sample visitor that generates markdown content from member summaries:

    public class MarkdownVisitor : Visitor
    {
        public override void VisitMember(Member member)
        {
            Console.WriteLine();
            Console.WriteLine(new string('-', 50));
            Console.WriteLine("# " + member.Id);
            base.VisitMember(member);
        }

        public override void VisitSummary(Summary summary)
        {
            Console.WriteLine();
            Console.WriteLine("## Summary");
            base.VisitSummary(summary);
        }

        public override void VisitRemarks(Remarks remarks)
        {
            Console.WriteLine();
            Console.WriteLine("## Remarks");
            base.VisitRemarks(remarks);
        }

        public override void VisitExample(Example example)
        {
            Console.WriteLine();
            Console.WriteLine("### Example");
            base.VisitExample(example);
        }

        public override void VisitC(C code)
        {
            // Wrap inline code in ` according to Markdown syntax.
            Console.Write(" `");
            Console.Write(code.Content);
            Console.Write("` ");

            base.VisitC(code);
        }

        public override void VisitCode(Code code)
        {
            Console.WriteLine();
            Console.WriteLine();

            // Indent code with 4 spaces according to Markdown syntax.
            foreach (var line in code.Content.Split(new[] { Environment.NewLine }, StringSplitOptions.None))
            {
                Console.Write("    ");
                Console.WriteLine(line);
            }

            Console.WriteLine();
            base.VisitCode(code);
        }

        public override void VisitText(Text text)
        {
            Console.Write(text.Content);
            base.VisitText(text);
        }

        public override void VisitPara(Para para)
        {
            Console.WriteLine();
            Console.WriteLine();
            base.VisitPara(para);
            Console.WriteLine();
            Console.WriteLine();
        }

        public override void VisitSee(See see)
        {
            var cref = NormalizeLink(see.Cref);
            Console.Write(" [{0}]({1}) ", cref.Substring(2), cref);
        }

        public override void VisitSeeAlso(SeeAlso seeAlso)
        {
            var cref = NormalizeLink(seeAlso.Cref);
            Console.WriteLine("[{0}]({1})", cref.Substring(2), cref);
        }

        private string NormalizeLink(string cref)
        {
            return cref.Replace(":", "-").Replace("(", "-").Replace(")", "");
        }
    }

There are two logically separated hierarchies of visitable elements: the members (like the whole set read by the Reader, a type, method, property, etc.) and the documentation elements (like summary, remarks, code, etc.).

The following is the members hierarchy:

Members hierarchy

And this is the supported documentation elements hierarchy:

Members hierarchy

Note that at the visitor level, both hierarchies are treated uniformly, since they all ultimately inherit from Element. In this fashion, you can have one or multiple visitors processing different parts of the graph, such as one that processes members and generates individual folders for each, and one for documentation elements that generate the content.

Enjoy! Go get it now from NuGet ;)

Comments

5 Comments

  1. Good Article. Any idea if this is supporting .Net 4.0 WCF Rest API documentation as well? I was faced with an issue, where the documentation did not have access to the Service Description for the REST Api etc.

    • Good question. Honestly, this should be able to read any .xml documentation file you throw at it. The unit tests do it with all .NET platforms and it just works.

  2. Your initial idea, using this to create wiki pages in a github repo, is something I’ve been thinking would be a good idea for the past couple weeks. Have you started, or are going to start on that part soon? If you’re going to host that code on github too, i’d love to help if I can.

  3. Yes, we’ve been working for the last couple weeks on generating full sites out of assemblies. We’re in the process of making sure this works on as broad a sample as we can gather, but we haven’t yet decided on the hosting for the markdown files. There’s some html and javascript that’s needed in order to have a usable and navigable/searchable API doc, so it’s not as simple as I initially thought, but we’re pushing hard towards fully static sites, absolutely.

    Will post more info when we’re ready :)