Documenting Your Code with XML and Sandcastle

[sbeadle1]

📖 Home  Back  

Document in the Source Code

You can document as you develop - instead of having to painstakingly retrace your steps months later - by exploiting Visual Studio's XML documentation support. Visual Studio enables you to embed your comments in XML tags inside your code, then extract them to a free-standing XML file. The file can be marked-up any way you please or - best of all - the documented code can be passed straight to Sandcastle to simply and easily produce help files that can be referenced as needed.

The process is automated; Visual Studio will create and extract the tags for you. Type

'''

on the line before a member and Visual Studio will create the tags required to document it.

Tick the "Generate XML documentation file" box in Project -> Properties and Visual Studio will extract the tags to a file each time you compile. Visual Studio's built-in XML schema provides a wealth of functionality, including tags for hyperlinks and code samples. It also allows you to add tags of your own.

Sample

''' 
''' Adds up all of the elements in an array of uintegers.''' 
''' 

Resources

MSDN Visual Basic Programming Guide: Documenting Your Code with XML

Use Sandcastle to Generate Help Files

Sandcastle Help File Builder is a free tool that transforms XML-documented files into fully-featured Windows help (.CHM) files, complete with Contents, Index and Search functions, .NET language and scope filters, and inheritance hierarchy hyperlinks.

Once the Builder is set up, it's simple to use. All you have to do is create a project, add the files that you want to build from, and click "Build Project". Building can take a few minutes but the results are worth the wait. Needless to say, you need to have documented your code in XML beforehand.

Requirements

In order to use Sandcastle Help File Builder, you will need:

• .NET 2.0 Framework.

• Sandcastle CTP.

• HTML Help Workshop.

Go: Home Back