I know we as programmers like to write code. However, most of the time we don’t get to start from the beginning. Most often we get to modify and enhance code that has been written by someone else. Let’s make a deal, from now on let’s document our code so we don’t have to spend so long trying to figure out what is going on.
Within Visual Studio you can place your documentation within XML tags and then use Sandcastle to make a nice CHM (help) file.
To turn on the XML Documentation functionality, you need to right-click on your project and select Properties. Then on the Build tab check the XML documentation file check box.
Then, above each method, property, class, etc.… you want documented, enter in 3 forward slashes like this – /// and a default structure will be created for you like the below.
/// <summary> /// Add Summary of method, property, class, etc. here /// </summary> /// <param name="parameterA"> /// add parameter description and type here</param> /// <returns> /// add description of what the method returns here /// </returns>
When you compile your program the XML documentation is created. You will be able to find your XML documentation file in your projects working folder (I.e. /bin/Debug) and it should be named Assembly_Name.XML (where assembly name is the name of your C# assembly). Can be VB or C++ too…
Once you have clearly documented all your code and created the XML documentation file (by enabling the XML Documentation checkbox and compiling your program), you will need to download, install and configure Sandcastle. For this example I installed:
- NOTE: I am installing on Windows 7 64bit with Visual Studio 2010 Professional already installed.
- Sandcastle Help File Builder version SHFB v184.108.40.206 – (SandcastleBuilderSetup_1910.zip) which I downloaded here
- 2. Followed by the Sandcastle.msi version 2.4.10520 which I downloaded from the Microsoft Download Center.
- 3. Then I applied this patch – SCPatch_Jun2010_2_6_10621_1_Rev1.zip which I downloaded from here on top of what I installed in step 2.
Installing Sandcastle was the hardest thing for me to do out of the 3. Configuring it and generating the CHM file is simple.
Open Sandcastle. You do this by going to the directory where you installed step 1 and find the Application (EXE) file named SandcastleBuilderGUI and double-click it. You can create a short-cut to your desktop too if you will use it often.
Configuration of the tool is very specific to your specific program. However, I will provide some information about what I did here, just for reference. It may or may not work for you.
The first things I did was to add my documentation sources. This is the XML file that gets created when you compile your program. Right-click Document Sources and select Add Document Source… that are located in the Project Explorer window, like below.
If you have any references required for your program to run, add them to the Reference folder. For example, something like the NHibernate components or WPFTools, etc.…
Then build the output and that’s it. You have just created a nice help file with hyperlinked pages. This really will help if another programmer needs to read about your code before they begin to modify or enhance it. Remember, documentation is good!