Getting started with the Live Documenter

The Live Documenter is a .NET documentation viewer. It opens up the information stored in all of those XML tags and makes them available, quickly.

Here is a little introduction to help get your documentation displayed in the Live Documenter.

Solutions, projects and libraries

To start you just simply need to point the application at a Visual Studio solution or project file. Or if you want to only view the documentation associated with a single library you can do that too. After a couple of fleeting seconds the application will show you all of the compiled libraries you have selected. The colour of the names of the assemblies let you know if there is documentation linked to them; black text means the comments have been found and loaded, grey means that no documentation has been found. This is generally because the XML comment file has not been output by the compiler.

grey text means no documentation was found

Make Visual Studio output your code comments

View of the output XML code comments option in Visual Studio

Setting the XML option

Visual Studio has a property setting that informs the compiler it should output the XML code documentation as part of the build process. If you do not have this set you will find that there are no comments for any of your libraries. You will need to set the property for each of the projects in your solution. For each project, right click the project and select properties. In the properties window select build and at the bottom (seen below) is the check box. Check it, save, recompile and you have output your comments.

.NET XML comments

The Live Documenter supports all of the .NET XML documentation comments here is a quick list of the documentation comments and a few screen shots of how they are displayed in the Live Documenter.

Name Description
c Inline text you would like to indicate as code
code A block of code, allows multiple lines
example Generally used to provide an example of how to use a library method or member. Generally used in conjunction with the <code> documentation.
exception Allows you to describe the exceptions that a library member could throw. And a description of the exception
list And associated documentation elements allow you to write a bulleted list of points.
para A paragraph of text
param Used to describe a parameter on a method.
paramref Allows you to refer to method parameters inline in other block level elements such as para or summary.
permission Allows you to document the access to a method or member.
remarks Allows you to supplement the information provided in the summary.
returns Allows you to describe the value returned by a method or property
see Allows you to refer to other members inline in the documentation. Can be used in para and summary elements for example.
seealso A list of associated members
summary A description of the method or member
typeparam Allows you to describe the generic types type parameter
typeparamref Allows you to refer inline to the generic types type parameter
value Allows you to describe the value that a property contain

The summary, remarks and see XML tags can be used to provide the bulk of the comments associated with any class, method etc. See XML tags will be automatically linked to the correct member in Live Documenter.

View of summary, remarks, see XML comments

You can use the param and exception XML comment tags to provide detail about what is expected of a parameter and what exceptions developers can except to handle from the method.

View param and exception comments in live documenter

There are many more XML tags then is sensible to write about here. We will provide more tutorials on how to use the Live Documenter and how to get the most out of your documentation.

Viewing your documentation

Searching

So now we have our code documentation in front of us. How can we better use the Live Documenter? Well firstly the search field allows you to type a portion of a member name and it will display a list of all the matched members across the whole solution. The results also show you a portion of the summary text and an icon so you can figure out what is what.

Live Updates

Whenever you update your documentation and recompile, normally you would need to re-export your compiled help file. With the Live Documenter it notices a library has changed and updates itself automatically. It’s nice and subtle, you will hardly notice it. Give it a try, modify the documentation of the class you are looking at. Compile and view it again. Nice huh!

Don’t like C#?

You can change the syntax blocks to display in other languages. Currently the Live Documenter supports C# and VB.NET. Navigate the menu, tools then preferences. You can then change the “Syntax language”. After changing browse and see the VB syntax instead.

Let’s make it better

Your feedback and support will help make this documenter better. We always want to hear what you have to say. You can keep up to date and tell us your thoughts on Twitter. Contact us at support@theboxsoftware.com.

Submit a Comment

Your email address will not be published. Required fields are marked *