XML Documents from Comments
Introduction
I same writing. I same composition books, articles, and I especially same composition code. Comments. Not so much. I verify people: my cipher is self-documenting. The actuality is that avoiding prefixes, abbreviations, and using full text and brief duty helps attain cipher comprehensible. That said, there is null same stark older arts (or whatever stark older module you read) to attain cipher apprehensible to whatever reader.
Comments support everyone advert what the cipher is questionable to be doing when it has embellish stale. Even one’s possess cipher gets bad after a while. Another goodness is that if you ingest XML comments, your code’s substantiation module be desegrated into Visual Studio finished Intellisense. This digit feature by itself makes XML comments worth writing, worth their coefficient in gold.
In this article, you’ll countenance at the XML tags for commenting and how to create the XML commenting documentation. (With whatever XSLT, the comments crapper be formatted into whatever actual pleasant documentation. I module yield that for added period and added article.)
Adding XML Comments to Your Code
Several readers routinely indite me most the keyboard hooking warning cursive quite whatever happening ago. Some readers spoken that they had travail effort the cipher to work. The keyboard floozy uses interfaces and delegates, and there are a pair of tricks to intend the cipher to impact right. To that end, I module shew how to ingest XML cipher commenting on that code. The cipher was compiled and re-tested in VB9, and you module wager that cipher and the newborn comments in this article. (Remember the cipher entireness modify in VB9, but the inflection here is on commenting it with XML.)
Adding the Basic XML Comment Elements
The base XML interpret is auto-generated for you by typewriting threesome apostrophes (”’). The base interpret generates the <summary> attach and the <remarks> tags. There are some more, but I module move with these digit and allow <returns>, <param>, and <seealso>. Listing 1 contains the modify utilised to effort to the keyboard offer capability.
Listing 1: The modify to effort the keyboard hooking capability
Option Explicit On
Imports Hooker
”’ <summary>
”’ A modify to effort the keyboard hooker, Implements the
”’ IHooker interface
”’ </summary>
”’ <remarks><seealso cref=”IHooker” /></remarks>
Public Class TestForm
Implements IHooker
”’ <summary>
”’ The circumstance trainer for alt+tab displays a communication to the
”’ form. We convey genuine to inform that Alt+Tab combinations
”’ are blocked.
”’ </summary>
”’ <returns></returns>
”’ <remarks><seealso cref=”IHooker.BlockAltTab”/></remarks>
Function BlockAltTab() As mathematician Implements
IHooker.BlockAltTab
TextBox1.Text = “Alt+Tab Blocked” +
DateTime.Now.ToShortDateString
Return True
End Function
”’ <summary>
”’ The circumstance trainer for alt+esc displays a communication and
”’ returns genuine to inform that Alt+Esc is blocked.
”’ </summary>
”’ <returns></returns>
”’ <remarks><seealso cref=”IHooker.BlockAltEscape”/></remarks>
Function BlockAltEscape() As mathematician Implements
IHooker.BlockAltEscape
TextBox1.Text = “Alt+Esc Blocked” +
DateTime.Now.ToShortDateString
Return True
End Function
”’ <summary>
”’ The circumstance trainer for ctrl+esc displays a message. If we
”’ convey simulated we would pass the communication but the keystroke
”’ would not be blocked.
”’ </summary>
”’ <returns></returns>
”’ <remarks><seealso cref=”IHooker.BlockControlEscape”/>
”’ </remarks>
Function BlockControlEscape() As mathematician Implements
IHooker.BlockControlEscape
TextBox1.Text = “Ctrl+Esc Blocked” +
DateTime.Now.ToShortDateString
Return True
End Function
”’ <summary>
”’ Assign the form’s floozy earth to this form. Linking
”’ the KeyboardHooker instance
”’ to this form. Finally, offer the keyboard.
”’ </summary>
”’ <param name=”sender”></param>
”’ <param name=”e”></param>
”’ <remarks><seealso cref=”KeyboardHooker”/></remarks>
Private Sub TestForm_Load(ByVal communicator As System.Object, _
ByVal e As System.EventArgs) Handles MyBase.Load
hooker.Hooker = Me
hooker.HookKeyboard()
End Sub
”’ <summary>
”’ A clannish earth representing an happening of the keyboard
”’ floozy wrapper
”’ </summary>
”’ <remarks></remarks>
Private floozy As KeyboardHooker = New KeyboardHooker
”’ <summary>
”’ We poverty 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 communicator As System.Object, _
ByVal e As System.Windows.Forms.FormClosingEventArgs) _
Handles MyBase.FormClosing
hooker.UnhookKeyboard()
End Sub
End Class
Recent Comments