You need to do two things to set up your .NET project for source code documentation with Help+Manual and Sandcastle:
1.Comment your code
2.Set one configuration option in the project.
Basic procedure: To create documentation for your code you need to insert XML elements in special comment fields, which you identify by using triple slashes instead of the usual double slashes. Insert these comment fields in the source code directly before the code block to which the comments refer, like this: /// <summary> /// The summary generally comes first. This summary would be /// for the class level documentation. </summary> /// <remarks> /// You can use the remarks tag for longer comments</remarks> public class WidgetConfabulator : TestInterface { /// <summary> /// Store for the realname property.</summary> private string _realname = null;
/// <summary> /// The class constructor. </summary> public WidgetConfabulator() { // This is a normal comment with two slashes and no XML tags } } When you compile with comments file option activated (see below) the XML documentation file used by Sandcastle will generated from the XML tags in your triple-slash comments. Sandcastle XML Comments Guide For full details on the XML comments supported by Sandcastle see the comprehensive Sandcastle XML Comments guide maintained by Eric Woodruff, the originator and manager of the Sandcastle Help File Builder project: Important warning: There are a some tags and elements described in the guide that are only supported by Sandcastle Help File Builder. These are identified in the guide and they should not be used with projects that you are going to document with Help+Manual without Help File Builder (which you can't use with Help+Manual, because HM then performs the function of Help File Builder). |
The other requirement is to configure your project in Visual Studio so that it will generate the XML documentation file from your Sandcastle comments and XML tags. To do this open your development project in Visual Studio and go to the Project Properties > Build section. Scroll down to the Output heading, enable the the XML documentation file option and enter a suitable name for it. Alternatively you can also compile your assemblies with the documentation switch and the comments file name: /doc:comments.xml  |
