XML Documents from Comments

Introduction

I like writing. I like writing books, articles, and I especially like writing code. Comments. Not so much. I tell people: my code is self-documenting. The truth is that avoiding prefixes, abbreviations, and using whole words and short function helps make code comprehensible. That said, there is nothing like plain old English (or whatever plain old language you read) to make code comprehensible to any reader.

Comments help everyone remember what the code is supposed to be doing when it has become stale. Even one’s own code gets stale after a while. Another benefit is that if you use XML comments, your code’s documentation will be integrated into Visual Studio through Intellisense. This one feature by itself makes XML comments worth writing, worth their weight in gold.

In this article, you’ll look at the XML tags for commenting and how to generate the XML commenting documentation. (With some XSLT, the comments can be formatted into some real nice documentation. I will leave that for another day and another article.)

Adding XML Comments to Your Code

Several readers routinely write me about the keyboard hooking example written quite some time ago. Some readers expressed that they had difficulty getting the code to work. The keyboard hooker uses interfaces and delegates, and there are a couple of tricks to get the code to work right. To that end, I will demonstrate how to use XML code commenting on that code. The code was compiled and re-tested in VB9, and you will see that code and the new comments in this article. (Remember the code works even in VB9, but the emphasis here is on commenting it with XML.)

Adding the Basic XML Comment Elements

The basic XML comment is auto-generated for you by typing three apostrophes (”’). The basic comment generates the <summary> tag and the <remarks> tags. There are many more, but I will start with these two and include <returns>, <param>, and <seealso>. Listing 1 contains the form used to test to the keyboard hook capability.

Listing 1: The form to test the keyboard hooking capability

Option Explicit On
Imports Hooker


''' <summary>
''' A form to test the keyboard hooker, Implements the
''' IHooker interface
''' </summary>
''' <remarks><seealso cref="IHooker" /></remarks>
Public Class TestForm
   Implements IHooker

   ''' <summary>
   ''' The event handler for alt+tab displays a message to the
   ''' form. We return true to indicate that Alt+Tab combinations
   ''' are blocked.
   ''' </summary>
   ''' <returns></returns>
   ''' <remarks><seealso cref="IHooker.BlockAltTab"/></remarks>
   Function BlockAltTab() As Boolean Implements
      IHooker.BlockAltTab
      TextBox1.Text = "Alt+Tab Blocked" +
         DateTime.Now.ToShortDateString
      Return True
   End Function

   ''' <summary>
   ''' The event handler for alt+esc displays a message and
   ''' returns true to indicate that Alt+Esc is blocked.
   ''' </summary>
   ''' <returns></returns>
   ''' <remarks><seealso cref="IHooker.BlockAltEscape"/></remarks>
   Function BlockAltEscape() As Boolean Implements
      IHooker.BlockAltEscape
      TextBox1.Text = "Alt+Esc Blocked" +
         DateTime.Now.ToShortDateString
      Return True
   End Function

   ''' <summary>
   ''' The event handler for ctrl+esc displays a message. If we
   ''' return false we would display the message but the keystroke
   ''' would not be blocked.
   ''' </summary>
   ''' <returns></returns>
   ''' <remarks><seealso cref="IHooker.BlockControlEscape"/>
   ''' </remarks>
   Function BlockControlEscape() As Boolean Implements
      IHooker.BlockControlEscape
      TextBox1.Text = "Ctrl+Esc Blocked" +
         DateTime.Now.ToShortDateString
      Return True
   End Function

   ''' <summary>
   ''' Assign the form's hooker field to this form. Linking
   ''' the KeyboardHooker instance
   ''' to this form. Finally, hook the keyboard.
   ''' </summary>
   ''' <param name="sender"></param>
   ''' <param name="e"></param>
   ''' <remarks><seealso cref="KeyboardHooker"/></remarks>
   Private Sub TestForm_Load(ByVal sender As System.Object, _
      ByVal e As System.EventArgs) Handles MyBase.Load
      hooker.Hooker = Me
      hooker.HookKeyboard()
   End Sub

   ''' <summary>
   ''' A private field representing an instance of the keyboard
   ''' hooker wrapper
   ''' </summary>
   ''' <remarks></remarks>
   Private hooker As KeyboardHooker = New KeyboardHooker

   ''' <summary>
   ''' We want to unhook the keyboard before we close
   ''' the application.
   ''' </summary>
   ''' <param name="sender"></param>
   ''' <param name="e"></param>
   ''' <remarks><seealos cref="KeyboardHooker.UnhookKeyboard"/>
   ''' </remarks>
   Private Sub TestForm_FormClosing(ByVal sender As System.Object, _
      ByVal e As System.Windows.Forms.FormClosingEventArgs) _
      Handles MyBase.FormClosing
      hooker.UnhookKeyboard()
   End Sub

End Class