XML Documents from Comments
If you want to read the original article, refer to "Managing Low-Level Keyboard Hooks with the Windows API". For your convenience, the complete listing for this version of the keyboard hook was uploaded with the article to codeguru.com.
Generating XML Documentation
The benefits of XML documentation include well-commented code in a uniform format, and your comments will be incorporated into Visual Studio's Intellisense system (see Figure 1) and Visual Studio will generate an .xml documentation file. (There are some tools that will convert these files to formatted help document too. Check out NDoc by Googling it.)
Figure 1: My XML comments are incorporated in the Intellisense system.
The XML documentation is generated by default. Generating documentation is equal to the /doc command line compiler option and is represented in the IDE in the Project Properties Compile tab by the (checked) checkbox next to the Generate XML documentation file (see Figure 2).
Figure 2: XML Documentation is configured to be generated by default.
I made excuses not to comment much for years. My code was self-commenting. Comments in code are ugly. (I still think they are.) And, I still submit that short, well-named methods help readability and debugging code gets stale and there is nothing like plain text to refresh one's memory (especially as the years collect).
With XML documentation, comments are well-formatted and uniform. They are automatically generated as XML files that easily can be converted into professional help documentation, and best of all, XML comments are incorporated into Microsoft Visual Studio's Intellisense system. Nothing beats Intellisense for quickly figuring out which element to use and how.
Download the Code
You can download the code that accompanies this article here.
About the Author
Paul Kimmel is the VB Today columnist for www.codeguru.com and has written several books on object-oriented programming and .NET. Check out his upcoming book LINQ Unleashed for C# due in Spring 2008. You may contact him for technology questions at firstname.lastname@example.org.
If you are interested in joining or sponsoring a .NET Users Group, check out www.glugnet.org. Glugnet opened a users group branch in Flint, Michigan in August 2007. If you are interested in attending, check out the www.glugnet.org web site for updates.
Copyright © 2007 by Paul T. Kimmel. All Rights Reserved.
Page 3 of 3