.NET Documentation in Live Documenter

Posted by Barry Jones in .NET, CLR, Development Jul 28th, 2010 | no responses

Today The Box Software released their .NET documentation tool the Live Documenter. There are certainly other tools to output static compiled help files. But the Live Documenter is different.

After we have painstakingly entered all of that XML code comments in our source code. We need a nice way to see the fruits of our labours. NDoc emerged years ago and provided a way to get your documentation in to a compiled CHM file, but crashed and burned when generics was released in .NET 2. Documentation tools/generators whatever have never kind of cut the mustard since then.

Lets have a look at the Live Documenter.

.NET documentation has never looked so good

The Live Documenter supports all currently available versions of the .NET framework, project and solution files. So when you want to view your documentation you can just simply point it at your current solution file. You will be greeted by the library view.

You are presented with a list of all of the libraries in the solution. The black ones have XML comments the grey ones have not. When you select one of the libraries the list of namespaces is displayed in the reading panel on the right. Nice and simple.

Lets just jump in and see what a documented class looks like.

The class is displayed as you expect. The remarks you entered are displayed, the see links you created are displayed AND they link through to the associated class, method, property. The inheritance tree is displayed and the see also links from the documentation. The tree view shows all the other classes, enumeration, interfaces in the same namespace.

/// <summary>
/// The AssemblyDef provides the top level information and entry point to
/// all types, methods etc reflected from a .NET executable.
/// </summary>
/// <remarks>
/// <para>The AssemblyDef is the starting point for obtaining reflected information
/// about a .NET assembly. This information is obtained by parsing and discerning
/// information about <see cref="TypeDef"/>s, <see cref="MethodDef"/>s etc from
/// the .NET metadata stored in the <see cref="PeCoffFile"/>.</para>
/// <para>The assembly implements a mechanism for generating unique identifiers
/// that can be assigned to each of the elements reflected in this assembly. The
/// unique identifier is not really required but can help other applications to
/// store keys and find reflected elements more quickly and uses less memory than
/// string based unique identifiers.</para>
/// <example>
/// <code>
/// // Instantiate from a full file path and name
/// AssemblyDef assembly = AssemblyDef.Create(myAssemblyPath);
///
/// // Instantiate from an already existing loaded metadata file
/// PeCoffFile peCoffFile = new PeCoffFile(myAssemblyPath);
/// AssemblyDef assembly = AssemblyDef.Create(peCoffFile);
/// </code>
/// </example>
/// </remarks>
/// <seealso cref="PeCoffFile"/>

There is a full list of supported XML tags on the MSDN website.

The method view is just as good. It displays the exceptions, type parameters, parameters, summaries and remarks as expected.

You can also search the whole solution for methods, classes etc. The Live Documenter will show you an auto-complete search box with the results for you query.

It handily displays the summary text with each result to help you figure out which result you was actually looking for.

There is plenty more to get excited about with the Live Documenter, it’s super fast, really good looking and I suggest you download your FREE copy from http://theboxsoftware.com/products/live-documenter/.