Have you ever considered adding documentation to your code instead of maintaining a separate word document as part of your application high level and detailed design? Let me start this series with the basics of generating help documentation and I will describe the different XML tags available for documentation and how we can generate our design documents out of XML comments in later articles of the series.
Visual studio.NET provides XML comments to enable documentation to be generated out of code. To generate XML documentation, open the project's properties dialog and select the "Build" tab. Check (select) the "XML documentation file" checkbox under "Output" section as shown in the image.
On rebuilding the project Visual studio.NET will generate an XML file named WebApplication1.XML(It is usually named after the project) in the bin folder. This XML file contains the XML documentation added to the code along with the Type information like Namespace, class name, methods and properties in the Type.
Here's a sample code annotated with XML comments
The XML file generated using Visual Studio.NET contains the Type information from the project as well as the XML comments added in code. Here's a portion of the XML file.
So far so good. We have laid the foundation for generating the documentation. We have, so far extracted the information we need and the next step is to transform this information into a more usable format. Open source and free tools are available to convert this data into a more readable format like Compiled Html Help files (chm) or Web pages and so on. NDoc (http://ndoc.sourceforge.net/) was one such project. Extremely useful but unfortunately it is no longer being updated. Another alternative is Microsoft's internal documentation tool - Sand Castle. (http://blogs.msdn.com/sandcastle/). This tool is available as a free download and can be used to generate Compiled Html Help format or Web based documentation for your code. I will cover using Sand Castle in the next post in this series.
Hope you enjoyed this part. In the next article in this series, I will talk more about Sand Castle.
Currently rated 4.0 by 1 people
- Currently 4/5 Stars.
- 1
- 2
- 3
- 4
- 5