In this writing I will explain you how to use SHFB for complete your class library documentation. This writing is only valid for .NET 3.0 or higher. In this piece of writing I am using Visual Studio 2008 for demonstration.
An API document of an application is one of the dullest tasks for each and every one of developer. Before VS 2008 there is an application called “NDoc” makes it very easy for everyone. But NDoc does not provide support .NET 3.0 or higher. In this article, I will try to explain how you can use SHFB to generate MSDN style documentation for your .NET assemblies build on .NET 3.0 or Higher.
What do I mean by SHFB?
SHFB stands for “Sandcastle Help File Builder”. Sandcastle, created by Microsoft, is a tool used for creating MSDN-style documentation from .NET assemblies and their associated XML comments files. The SHFB can produce an HTML Help 1.x (.CHM) file, an HTML Help 2.x (.HxS) file, and/or a website.
How much it will cost?
This is created by Microsoft. So you may asked, how much it will cost!!! But this product is totally free comes under Microsoft Public License (Ms-PL) as like many other projects of Microsoft. The project is hosted at CodePlex in the Sandcastle Help File Builder project. You can download it by click here.
How to use it?
I do not like go through with the entire installation step. It is very easy to install. You can find the details in Installation Instructions of SHFB. Please make sure that everything is configured correctly.
How to generate the XML file?
If you have already known how to generate the XML from your code, you may skip this part. I am guessing that you have already comments you code. Now please open your class library solution. Right click the class library project and select “Properties”.
Under the “Build” tab there is “output” area. Check the “XML documentation file”. Now build you project, you will spot the documentation file in XML format in allocated location.
Add Assembly to SHFB Project
So now your project is almost ready for documentation. Guessing that you have already install SHFB. Open the SHFB GUI from user start menu. Select “File > New Project” from menu. Save the project using “Save as” dialog box. Right click on the “Documentation Sources” node in the “Project Explorer”.
In the context menu, please select “Add Documentation Source” for add the assembly file. Browse and select you class library assembly file. XML file will be automatically added, if associate XML file is found in same place. You may change some properties value in “Project Properties” such as HelpTile, HeaderText, FooterText, CopyrightText etc...
You may also mention the help file format in this window. I am using “HtmlHelp 1x”.
Finish it up.
You have already add the assembly and made some change in “Project Properties”. Now build the file. You can see the “Build” button on toolbar window. Click on it.
That the enough work you have done. Now the entire build process message will display in the console made by GUI. If there is any error arises, please check the SHFB Help documentation according to the error code. After successfully complete the build process check the output directory you will find the *.chm file.
Congratulation!!! You have just made your first .NET assembly documentation in SHFB. There is lot more option in SHFB; I hope you will find it one by one.