Integrating documentation into Visual Studio.NET
From TanisWiki
Contents |
Introduction
Working on a project of any size, we all know how important good documentation is. Getting to write it is another issue though.
C# and the Microsoft.NET FrameWork has taken measures to help you with that. A XML documenting standard has been introduced that you write directly into the source code; much like Javadoc for Java.
In this article I will explain how to document using the XML tags, how to use NDoc to convert the XML into very nice looking HTML Help files, and last but not least, how to integrate the help into Visual Studio .NET.
Prerequisites
Before you can start documenting, you will need a couple of programs that are all available as free downloads:
After installing all of those, you should be ready to start creating nifty documentation, that will be available directly in Visual Studio as Dynamic Help and Intellisense.
Configuring XML commenting
First you need to enable your project to generate XML output. Follow these simple steps:
- Open the projects properties by right clicking on the project name in the Solution Explorer and clicking Properties.
- In the Properties window, click Configuration Properties and then click Build.
- Under Outputs, choose XML Documentation File and name the file appropriately. An appropriate name could be ".xml" or ".xml".
The XML Documentation will be rebuilt every time you build your project.
Any problem that occurs during building will be added to the Task List, where you can go through the problems and fix them.
Adding XML documentation to your code
Say you have a function that looks like this:
int GetScore(String PlayerName)
{
If you put your cursor on the line above and type three slashes, Visual Studio will automatically add this:
/// <summary>
///
/// </summary>
/// <param name="PlayerName"></param>
/// <returns></returns>
int GetScore(String PlayerName)
{
All you then do is fill in the missing description and you have documented your function:
/// <summary>
/// Gets the players score based on his <c>PlayerName</c>.
/// </summary>
/// <param name="PlayerName">The name of the player</param>
/// <returns>Returns the players score it is a valid <c>PlayerName</c>.
/// Returns -1 if the <c>PlayerName</c> was not found.</returns>
int GetScore(String PlayerName)
{
IntelliSense works automatically after compiling, so if you type this, you will get on-the-fly help:
There are quite a few tags that you can and should use when documenting. Here is a complete list:
| <c>text</c> | This tag gives you a way to indicate that text within a description should be marked as code. Use <code> to indicate multiple lines as code. |
| <code>content</code> | This tag gives you a way to indicate multiple lines as code. Use <c> to indicate that text within a description should be marked as code. |
| <example>description</example> | This tag lets you specify an example of how to use a method or other library member. Commonly, this would involve use of the <code> tag. |
| <exception cref="member">description</exception> | This tag lets you specify which exceptions can be thrown. This tag is applied to a method definition. |
| <include file='filename' path='tagpath(@name="id")> | This tag lets you refer to comments in another file that describe the types and members in your source code. This is an alternative to placing documentation comments directly in your source code file. |
| <list> | This tag lets you make a list or a table. The full syntax is as follows:
<list type="bullet" | "number" | "table">
<listheader>
<term>term</term>
<description>description</description>
</listheader>
<item>
<term>term</term>
<description>description</description>
</item>
</list> |
| <para>content</para> | This tag is for use inside a tag, such as <summary>, <remarks>, or <returns>, and lets you add structure to the text. |
| <param name='name'>description</param> | This tag should be used in the comment for a method declaration to describe one of the parameters for the method. |
| <paramref name='name'/> | This tag gives you a way to indicate that a word is a parameter. The XML file can be processed to format this parameter in some distinct way. |
| <permission cref='member'>description</permission> | This tag gives you a way to indicate that a word is a parameter. The XML file can be processed to format this parameter in some distinct way. |
| <remarks>description</remarks> | This tag is used to add information about a type, supplementing the information specified with <summary>. |
| <returns>description</returns> | This tag should be used in the comment for a method declaration to describe the return value. |
| <see cref='member'/> | This tag lets you specify a link from within text. Use <seealso> to indicate text that you might want to appear in a See Also section. |
| <seealso cref='member'/> | This tag lets you specify the text that you might want to appear in a See Also section. Use <see> to specify a link from within text. |
| <summary>description</summary> | This tag should be used to describe a type or a type member. Use <remarks> to add supplemental information to a type description. |
| <value>description</value> | This tag lets you describe a property. |
Using NDoc to produce great looking documentation
NDoc is a great and absolutely free tool, created by some very talented people. It makes it extremely easy to make your own documentation that can be presented directly inside Visual Studio.NET. Here is a look at my A* path finding class, presented in an earlier article:
To produce documentation that can be integrated into Visual Studio.NET, you must choose the "HtmlHelp2" documentation type in NDoc. Also give the help file a unique name:
After setting it up, all you need to do is build the documentation.
Using H2Reg to integrate the documentation into VS.NET
Usually, you would have to install a help file using a .msi install script. In this case, that is just way too much work. Fortunately, Helpware has made a small utility called H2Reg that can do it for us. It requires a configuration file and must be called from the command-line, so I thought a little helper program could make it a bit easier. There is a download link at the bottom of this article.
All you need to do now is fill in the fields and press Generate. The program will make a directory called "Help" in your project dir that will contain the configuration file, and two batch files that you can use to register and unregister the help files in Visual Studio.NET:
The help collection file you can find in the ./doc directory in your project directory (if you did not change the default NDoc directory, that is).
The program will generate the files in a directory called Help, one level above the NDoc directory. After you generate the files, you just need to run the register.bat batch file to register your help in Visual Studio.NET.
If you have problems with the collection not being registered have a look at H2Reg's log file called C:\Program Files\Helpware\H2Reg\H2Reg_Log.txt (assuming you installed it in the default directory).
Including the help into Visual Studio.NET
The help files have now been activated and integrated into the Visual Studio Help Collection. You might need to restart Visual Studio .NET if you have it running.
Now we have context sensitive help, Intellisense and dynamic help. Could you ask for more?
Conclusion
In a few simple steps, we have integrated help for our own code, pretty much all over the place.
To me this is really a productivity booster. What about you?
