Documenting C# Library using GhostDoc and SandCastle
Documentation is an essential part of any IT project, especially when you are creating reusable components that will be used by other developers (such as class libraries). Without documentation re-using a class library is almost impossible. Just think of coding .net applications without MSDN documentation (Ooops I can’t think of it).
Normally developers, who know the bits and pieces of their classes, see this as a boring work to write details again to generate the documentation. Also the amount of work to make this and manage it changes made the process of manual creation of Documentation impossible or tedious.
So what is the effective solution? Let me divide this into two steps
1. Generate comments for your code while you are writing the code.
2. Create documentation file using these comments.
Now I am going to examine these processes.
Step 1: Generate XML Comments automatically
Most of the developers write comments for their code. The best thing is that the comments will be entered during the development process. Additionally comments give a good reference to the code, make your code more manageable/readable. Later these comments can be converted into documentation, along with your source code by identifying properties and methods
I found an add-in for visual studio, GhostDoc that automatically generates XML documentation comments for C#. The add-in is available in Visual Studio Gallery at MSDN.
You can download this from the url http://visualstudiogallery.msdn.microsoft.com/en-us/46A20578-F0D5-4B1E-B55D-F001A6345748.
I downloaded the free version from the above url. The free version suits my requirement. There is a professional version (you need to pay some $ for this) available that gives you some more features. I found the free version itself suits my requirements. The installation process is straight forward. A couple of clicks will do the work for you. The best thing with GhostDoc is that it supports multiple versions of visual studio such as 2005, 2008 and 2010.
After Installing GhostDoc, when you start Visual studio, the GhostDoc configuration dialog will appear. The first screen asks you to assign a hot key, pressing this hotkey will enter the comment to your code file with the necessary structure required by GhostDoc.
Click Assign to go to the next step where you configure the rules for generating the documentation from the code file.
Click Create to start creating the rules. Click finish button to close this wizard.
Now you performed the necessary configuration required by GhostDoc. Now In Visual Studio tools menu you can find the GhostDoc that gives you some options.
Now let us examine how GhostDoc generate comments for a method. I have write the below code in my code behind file.
public Char GetChar(string str, int pos)
{
return str[pos];
}
Now I need to generate the comments for this function. Select the function and enter the hot key assigned during the configuration. GhostDoc will generate the comments as follows.
/// <summary>
/// Gets the char.
/// </summary>
/// <param name="str">The STR.</param>
/// <param name="pos">The pos.</param>
/// <returns></returns>
public Char GetChar(string str, int pos)
{
return str[pos];
}
So this is a very handy tool that helps developers writing comments easily. You can generate the xml documentation file separately while compiling the project. This will be done by the C# compiler. You can enable the xml documentation creation option (checkbox) under Project properties -> Build tab.
Now when you compile, the xml file will created under the bin folder.
Step 2: Generate the documentation from the XML file
Now you have generated the xml file documentation. Sandcastle is the tool from Microsoft that generates MSDN style documentation from the compiler produced XML file. The project is available in codeplex
http://sandcastle.codeplex.com/. Download and install Sandcastle to your computer.
Sandcastle is a command line tool that doesn’t have a rich GUI. If you want to automate the documentation generation, definitely you will be using the command line tools. Since I want to generate the documentation from the xml file generated in the previous step, I was expecting a GUI where I can see the options.
There is a GUI available for Sandcastle called Sandcastle Help File Builder. See the link to the project in codeplex. http://www.codeplex.com/wikipage?ProjectName=SHFB. You need to install Sandcastle and then the Sandcastle Help file builder.
From here I assume that you have installed both sandcastle and Sandcastle help file builder successfully. Once you installed the help file builder, it will be available in your all programs list.
Click on the Sandcastle Help File Builder GUI, will launch application. First you need to create a project. Click on File -> New project
The New project dialog will appear. Choose a folder to store your project file and give a name for your documentation project.
Click the save button. Now you will see your project properties.
Now from the Project explorer, right click on the Documentation Sources, Click on the Add Documentation Source link. A documentation source is a file such as an assembly or a Visual Studio solution or project from which information will be extracted to produce API documentation.
From the Add Documentation source dialog, I have selected the XML file generated by my project.
Once you add the xml file to the project, you will see the dll file automatically added by the help file builder. Now click on the build button.
Now the application will generate the help file. The Build window gives to the result of each steps. Once the process completed successfully, you will have the following output in the build window.
Now navigate to your Help Project (I have selected the folder My Documents\Documentation), inside help folder, you can find the chm file. Open the chm file will give you MSDN like documentation.
Documentation is an important part of development life cycle. Sandcastle with GhostDoc make this process easier so that developers can implement the documentation in the projects with simple to use steps.