Products
Database Search Solution (New Version) Search Control SEO Pager Highlighter Shortcut Controls Crypt Package Free ASP.NET Controls
Geotargeting Component ASP.NET Media Player Control Flash Video Player Control Services
ASP.NET Telecommute Jobs Free IP Location Lookup Test .Net Regular Expressions CSS/Table/DIV Page Layouts Custom Programming Article Sites Master List |
Automatic Documentation Generation in ASP.NET applicationsThe .NET Documentation ProblemNo one can disagree regarding the importance of documentation. Despite of this fact, software development documentation are not always produced as it should be. Many reasons can be proposed for this fact but regardless of all these reasons, the most contributing reason is the attitude of software developers themselves! Yes, this can be easily accepted if we recall the fact that many software development projects are late from their schedule and that software developers are typically stressed writing the code itself ..... Then how can you afford asking them to come more and more behind their schedule and waste their time writing documentation? The solution of this dilemma is the subject of our tutorial. Recall the simple fact that any software developer can be easily and successfully asked to put some simple comments lines in the source code he write. He does this as he writes his code line by line not at the end of development phases as some other documentation strategies suggest. Let's call this documentation strategy 'Clean As You Go!'. The pioneering idea here is that the documentation is not delayed to the end of development phases and then typically overlooked or poorly produced. Another great advantage is the fact that the documentation is inside the source code itself and hence the binding between them is in it's best case in this documentation strategy. Any slight change in the source code (which typically happens to take place many times during the testing and debugging phases of software development) can be easily and immediately reflected in the documentation in the same place. Contrast this with the other documentation strategies in which the process is much more expensive and takes much more time to the extend that stressed software developers either totally overlook the update or at least they poorly apply it! The SolutionSimply write all the documentation you need tightly tied to and inside your source code! Then use some documentation processing tools to collect all these comments and to construct a stand alone document containing every little aspect about your source code. As simple as that! In this tutorial we will present you an example of how to implement and benefit from this documentation strategy. Particularly we will cover a case that tutorials rarely (if never!) cover: The case of documenting ASP.NET 2.0 web applications using Microsoft Visual Studio 2005. Microsoft Visual Studio 2005 supports XML documentation comments for C# and Visual Basic.NET. Unfortunately, Microsoft Visual Studio 2005 does not currently support XML documentation comments for ASP.NET 2.0! This update is scheduled to be included in the next Visual Studio service pack (SP1). For now you will need to download and install 'Microsoft Visual Studio 2005 Update to Support Web Application Projects' and 'Visual Studio 2005 Web Application Projects add-in' (see [1] and [2] in the 'For further information' section at the end of this tutorial). All the above updates are just to enable the support of XML documentation comments in ASP.NET 2.0. The actual generation of comments is done using an open source tool (many times referenced by Microsoft) called NDOC. You will need to download and install NDOC for MSDN like documentation generation. For more information see [3] and [4] in the 'For further information' section at the end of this tutorial. But ... How?The general procedure you will use in such documentation technique is to write your comments inside your source code in a special notation that we will present shortly and then to use NDOC to generate MSDN like documentation from these comments. Let's illustrate this by an example. You can download this example here. First of all you need to know that so that you are able to benefit from this documentation technique then you need to create your new web application somewhat differently. Instead of selecting File / New / Website in Microsoft Visual Studio 2005, you will need to select File / New / Project / Visual Basic / ASP.NET Web Application or otherwise no XML documentation files will be generated. Let's add a new class to our web application. Click Project / Add Class and name your class as Class1. Here's the code you will need to add to this class:
Now build your web application and then browse to your web application folder and locate the XML file containing your XML documentation comments. This file should be with a name exactly as your web application but with an XML extension. Locate it specifically in the 'bin' folder. If we are to display that XML file we will find the following:
As you can see, all comments are automatically collected together in the same file and are now ready for conversion to MSDN like documentation. The XML to MSDN like documentationNow open your NDOC tool (NDocGui.exe) and click the add button. In the assembly ellipse (...) you will browse for the assembly of your web application (also in the bin folder with the same name as the web application but with a DLL extension). NDOC will then automatically enter the SlashDoc field for you. Now click the Documentation / Build menu item and you are done!!! Yes, you are done and you now have a file (Documentation.chm) that contains all of your documentation in a single MSDN like file! Let's view parts of it in figures 1, 2, and 3:
What is not supported?An important fact is worth mentioning here is that the documentation strategy presented in this chapter is not applicable for some types of documents, for example you cannot apply this documentation strategy for requirements collection and analysis documents, and you cannot apply it for user manuals and help documents. This documentation strategy is much more suited for source code documentation and the documentation schemes near from this. Another documentation feature that is not supported is the documentation at the level of functions. In other words comments inside functions are not included. To have your comments about a given function to be included in the final documentation then you have to write them on the top of your functions (inside the <summary> or the <remarks> tags for example). A a general rule of thumb, the documentation technique we presented here is most suited for documenting assemblies, classes, class members and functions mainly at the class level. For further information
Tutorial toolbar: Tell A Friend | Add to favorites | Feedback | |
