Monday, May 4, 2009

Code Documentation Manual using SandCastle

Before doing anything, go to the following link and download the latest version of SandCastle:
and if you really intuitive to drill down this tool and want to inspect how it works and want to make something more better based on this tool, you have the source code to download(
At that very moment I thought it must be a pluggable component (like other VS 2005 add-ins ) in VS 2005 environment. But, I didn’t found anything in VS2005 environment, so I was a bit confused (how to start and where to start?). I thought if there is some Hello World kind of thing, then life will be easy.
So I inspect the installation folder (in my workstation C:\Program Files\Sandcastle this may vary depending upon the desired location you have installed SandCastle). I found an folder Named as Examples, (so the total path becomes C:\Program Files\Sandcastle\ Examples). Inside Examples folder you will a folder named as generic (so now we are at C:\Program Files\Sandcastle\Examples\generic).
Here you will find an exe named as SandcastleGui.exe [Fig 1](That’s what I was searching for, a GUI based tool which will provide me the desired document without any long configuration change or alteration.)
Now before going for any code documentation using this tool, we need to do some homework.
1. Open the project for which you want to make the documentation
2. Open the Solution Explorer and right click on the project node and select Properties from the context menu.
3. Visual Studio will open a property page for the project.
4. Now select the Build tab, from the left navigation pane. In the right Detailed pane check the XML Documentation File check box.
1. Provide a destination file name and path.(This xml file contains all the code comments that are present in all the code files in your project.)
2. Now, save this project properties page.
3. Now we need to generate the assembly as well the xml comment file for this assembly.
4. Right click on the project node and select Build option from the context menu.

Now we are ready for the code document generation using SandcastleGui.exe

1. Double click the SandcastleGui.exe to run.
2. It will open a window something like-
1. This UI is quite self explanatory.
a. In the first segment (Assemblies) we need specify the assembly file for which we need to generate the code document.
b. The second segment (Comments) we just need to specify the XML file (the file we created during the build process of our assembly.)
c. The third segment is the dependent assembly.(which is optional, only valid for dependent assemblies)
d. Now, specify the name of the document file to be generated (Under Options section fill the name text area)
e. Now select the default target (I’ve checked the Chm check box to get the help file as .chm file).
2. After performing the above step (step 3), the UI will look something like -
1. Now press the build button.
2. The Log portion shows all the activities which are currently performed by the utlitity.
3. After sometime (it takes a bit time to generate the .chm file depending upon the assembly and dependent assembly) a build finished dialogue box will open and the chm file is ready.
4. Now to locate the .chm file by inspecting the last log entry
So now we are ready with a good looking code document in a .chm format.

No comments:

Post a Comment