Documenting VB.NET and C# Code

If you are using VB6 then you are possibly somewhat limited as to the way you can document your code and then have it published automatically. (I say that from complete ignorance and somebody is very welcome to show me otherwise). However in VB.NET and C# there is the built in XML documentation. In both languages you simply place the cursor the line above the field, property, method or class that you wish to document. In VB.NET you type:

'''

or in C# you type

///

You are then given a template depending on the language area you are documenting. For example below is the template you get for a property (shown in VB.NET)

 ''' <summary>
 '''
 ''' </summary>
 ''' <value></value>
 ''' <returns></returns>
 ''' <remarks></remarks>

This makes documenting much easier as you can then also add links to other code areas as example of which is shown below.

 ''' <summary>
 ''' Used to represent a phone number. Each phone number belongs to an <see cref="Address">Address</see>
 ''' </summary>
 ''' <value></value>
 ''' <returns></returns>
 ''' <remarks></remarks>

I have been documenting my code like this for many years but have never really done much with it. It has been there in order to make it easier for me to go back to and update if need be. However now I have discovered a utility that, I am sure, has been available probably as long as I have been documenting .NET code. Sandcastle is a tool from Microsoft that can be used to produce MSDN style documentation based on the XML comments in code. It uses the assemblies and the xml documentation that building your application produces (if you have the flag set in the project settings). Sandcastle by itself is somewhat difficult to use but combined with Sandcastle Help File Builder it works really well, creating really professional looking API documentation. All I need to do now is to document my code for each and every property and method to make it really useful!

One thought on “Documenting VB.NET and C# Code

  1. Thanks for this… I had no idea it existed.

    Though I’ve always wondered what the warning “XML comment cannot appear within a method or a property. XML comment will be ignored.” meant when I had typed ”’ when adding comments throughout code.

Comments are closed.