I'm constantly annoyed by the number of developers using Visual Studio.NET who don't seem to see the need to create decent documentation for their classes. Hey! Who cares about other people who may have to use my code! Let the Dorks eat Oreos, right? You come into an organization; the person who wrote the code you now have to work with no longer works there, and -- if you are lucky -- the only documentation you can find is a few C-style comments interspersed in the code - and usually, they are the cryptic kind that only the original developer would understand!
With Visual Studio.NET there is no excuse for this kind of shoddy development practice. None, zero, zippo, nada, efes! With a minimum of study and a couple of free tools, you can make first-class MSDN style CHM Help files (as well as web-based documentation) for your creations. You can apply XSL transformations to the generated XML to port your documentation to other media such as MS Word. Other developers will respect and thank you; your manager will too, and your professional credibility as a developer will be greatly enhanced. The formula is simple: You want to be a professional developer? Then don't make excuses -- create professional documentation!
As most developers know, Visual Studio.Net supports XML code comments in C#, and there are add-ins available for Visual Basic.NET and C++.NET as well. For the most basic of documentation, you can get the free GhostDoc add-in by Roland Weigelt. To put it in perspective:
GhostDoc is an add-in for Visual Studio .Net 2003 for automatically
generating those parts of a C# documentation comment that can be
deduced from name and type of e.g. methods, properties or parameters.
with GhostDoc turned on, just right-click above the signature of your method and choose "Document This". GhostDoc takes care of the rest. If you want to add more, learn a few XML tags specific to the Microsoft documentation scheme, and you are on your way. The next step is simply to set up your project for documentation:
- Open the Property sheet for the project.
- Click the Configuration Properties node.
- Click the Build option.
- In the "Xml Documentation File" area, enter the relative path and filename for your XML Documentation file to be saved.
Even without GhostDoc, during your coding, whenever you type three forward slashes, Visual Studio.NET sees that the first two slashes are a comment, and the third one tells the parser that this is an XML Comment. If your comment precedes an identifiable type or type member definition, the IDE will automatically insert a few of the most common XML Comment tags for <summary> and <param> (parameters).
I'm not going to go over the recommended XML comment tags here because there is already excellent documentation on them. If you have never taken the time to study them, please do so now.
The next step is to get the free NDoc utility here. NDoc generates class library documentation from .NET assemblies and the XML documentation files generated by the C# compiler (or with an add-on tool, for VB.NET).
NDoc uses pluggable documenters to generate documentation in several different formats, including the MSDN-style HTML Help format (.chm), the Visual Studio .NET Help format (HTML Help 2), and MSDN-online style web pages. And, it's so easy to learn to use, its almost a joke!
Finally, you'll need the HTML Help Compiler from Microsoft. This is the engine that creates CHM help files, and NDoc is engineered to work with it directly. You can download the HTML Help Workshop here, and you are ready to go.
|NDoc GUI Example|
Simply fire up the NDoc Windows GUI, point it at your compiled assembly and matching generated documentation XML file, select your favorite options, and press the compile button. The result is a professional MSDN-style CHM help file that you can add to your MSI Installer project or distrbute with your project. If you use Sourcesafe or another source code repository, you can add all this to your solution in source control as well. You will also notice that NDoc has generated a full set of HTML pages that can be placed on a Web site for online documentation as well.
This is a short article with a bunch of resource links. If you haven't ever done all the above steps, I promise you that taking the time to do them now will make you a better developer and a better team player in the enterprise. Are you up to this? Good luck!