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.
Make Visual Studio output your code comments
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.
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.
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
The Box Software is committed to providing a free non-commercial version of this product. 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 . Or raise your thoughts at user voice.
what if we want to buy commertial lisence
Currently the Live Documenter is a documentation viewer. We have been working on the export functionality. We are releasing this functionality with the ability to purchase commercial licensing in the first quarter of 2011.
Thanks for your enquiry.
Interesting, doesn’t seem to correctly support ≶list> tags:
///
/// Some text
///
///
/// A
///
/// The letter A
///
///
///
/// B
///
/// The letter B
///
///
///
///
Shows a bullet list with no text after the bullet
Sorry quoting didn’t make it
Here it is quoted:
/// <summary>
/// Some text
/// <list type="table">
/// <item>
/// <term>A</term>
/// <description>
/// The letter A
/// </description>
/// </item>
/// <item>
/// <term>A</term>
/// <description>
/// The letter A
/// </description>
/// </item>
/// </list>
/// </summary>
Also it doesn’t find the dll based on the info in the sln/csproj file (if the dll is not output to the default ./bin/debug dir)
Hi Static Shock, thanks for taking the time to post this. Both these issues are known and being resolved at the moment. These are going to be released soon, unfortunately they are held up in the larger release cycle which includes the export functionality.
IS there a way to not expose a clas or a method in the documentation by adding a directive?
Not in the current download version. We are looking in to ways to expand the current (beta) version from filtering simply from visibility to perhaps using an attribute or similar mechanism.
Thanks for your feedback.