We often writes a tons of code for each project and after awhile you are drifted to other projects, projects, and projects... We cannot avoid that we often forgot the objects, methods, properties, dependencies, and its business workflow. As a agile advocate, we tend to document our code while we are developing by adding inline comments. With Visual Studio and our buddy XML documentation tag gives more flavor in code documentation.

The XML Documentation tag is like a comment with tripple forward slash (///) in C#. It is use to document classes and its members (constructors, methods, properties), enums, delegates, events and more. When you type three forward slash (in C#) it will automatically create a basic code documentation template for you. See sample below.

/// <summary>
/// 
/// </summary>
/// <param name="parameter1"></param>
/// <param name="parameter2"></param>
/// <returns></returns>

Documentation is important especially if you are developing a library that will be consumed by other applications, products, and business applications. This will alow them to extend, support, and maintain the application.

Configuring Visual Studio Project to Generate XML Document File

This will allow the project to automatically generate the XML document everytime you successfully complie the project. This file will contain the xml documentation defined in the code. This file can be use to generate help file.

Follow this quick step to activate XML documentation.

  1. Open the Project Property from the Properties button of the object explorer or from the context menu of the project.
  2. On the Project Property, select Build tab.
  3. Check the Xml Documentation file checkbox.
  4. Save and close the Project Property tab.

In Sandcastle, XML documentation file is optional. You can generate help file using the solution file (*.sln), project file (*.csproj), assembly (*.dll), and executable (*.exe). As default all the objects (class, enums, etc) included in the project with or without the xml documentation tag (///) will be documented and included in the help file. You can configure help file output settings in Sandcastle's project properties or adding only assemblies and xml in Document Sources that you want to include in html help file.

So why generate XML Documentation file? The XML documentation allows you to isolate documentation to the selected XML documentation file by selecting only the file you want to include in your documentation. This also allows other platform or software to leverage Sandcastle's power to generate help file.

Lets Get it On

Follow the steps in installation wizard carefully.

Warning: During the process of installing Sandcastle you may required to restart your machine. Be sure to save the documents currenlty open.

  1. Download Sandcastle Help File Buidler installer at Codeplex.
  2. Run the SandcastleInstaller.exe to install Sandcastle. Read the instructions carefully during the installation process you may need to download dependencies along the way and may require you to restart your machine.
  3. Open Sandcastle Help File Builder GUI.
  4. Go to File -> New Project to create new project.
  5. Select the directory where you want to save the Sandcastle project.
  6. If the Project Explorer is not loaded, open it by selecting Windows -> Project Explorer.
  7. On the Project Explorer, right click the Documentation Source node and select Add Documentation Source from the context menu.
  8. Navigate to your solution (*.sln) file that contains the projects you want to document or specific Project File(s) you want to document. You can also create a Sandcastle project that includes combination of dll, exe, and xml.
  9. Before building be sure the FrameworkVersion in sandcastle's property window is set to the version of the files included in Documentation Sources  files. Also set the Compilation mode in the toolbar to the right mode. It should be the same as the compilation mode of the solution/project you included in the Document Sources.
  10. Click Build in the toolbar or go to Documentation -> Build Project menu to build the project. 
  11. After successfull build you can open the documentation file by selecting Documentaion -> View Help File -> View Help File. Now you have a professional MSDN style documentation in a fly.

For the record, my solution with around 25 projects tooks Sandcastle 20 minutes to build. If you have this number of projects in your solution, go grab some soda and watch tv after you press the buiild button. :)

Here are some of the basic information you need to change in Project Properties.

  • FrameworkVersion
  • ProjectSummary
  • CopyrightText
  • CopyrightHref
  • FeedbackEmailAddress
  • FeedbackEmailLinkText
  • FooterText
  • HeaderText
  • HelpTitle
  • HTMLHelpName
  • ProductTitle
  • VendorName

Build Error: Assembly Reference Missing

This ofen happen if you use assembly, executable, and/or XML document file as Document Sources. You need to reference the dependencies by adding it under Reference node. Its like adding reference in Visual Studio. In my case when I create my help file for my data access layer library, I need to reference Microsoft Enterprise Library.

In addition, Microsoft Enterprise Library enable XML documentation as default so you can add it in Document Source instead in Reference. In this case it will include Microsoft Enterprise Library in your help file which is much better. Either way will solve the reference issue.

If you receive missing SDK or can not locate SDK for specific framework, you need to download the .NET Framework SDK. After installing just rebuild the project.

Integrating Sandcastle Project in Visual Studio

Adding the Sandcastle Project in Visual Studio will give you quick access to Sandcastle project. Once added, you can double click the sandcastle project to launch the the Sandcastle Help File Builder GUI.

  1. Right click the Solution node. On the context menu select Add -> Existing Item.
  2. Navigate to the location where the Sandcastle project file is located and select the project file (*.shfbproj). This will add the file under Solution Items folder of the solution.
  3. If notepad or visual studio default xml editor is launched when you double click the sandcastle project file we need to map it to Sandcastle GUI. Follow these steps to map.
    • Right click the file and select the Open With from the context menu. This will open the Open With window.
    • From the Open With window select the Sandcastle Help File Builder and click Set as Default button
    • Click Ok button. You can now open Sandcastle project from Visual Studio by double clicking sandcastle's project file.

Where is NDoc?

NDoc is also a code documentation tool almost the same as Sandcastle but it does not support .NET Framework 2.0 and higher framework. This is the tool I used before for code documentation until Sandcastle is released. Sandcastle on the other hand supports all .NET Framework version including 4.0 that makes NDoc obsolete.

Dependencies

So far here are the list of dependencies.

References