Home
    Shop
    Advertise
    Write For Us
    Affiliate
    Newsletter
    Contact

Automatic Documentation Generation in ASP.NET applications

The .NET Documentation Problem

No 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 Solution

Simply 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:

 

    1 ''' <summary>
    2 ''' Summary for Class1
    3 ''' </summary>
    4 ''' <remarks>
    5 ''' Remarks for Class1
    6 ''' </remarks>
    7 Public Class Class1
    8     ''' <summary>
    9     ''' Summary for Variable1
   10     ''' </summary>
   11     ''' <remarks>
   12     ''' Remarks for Variable1
   13     ''' </remarks>
   14     Dim Variable1 As Integer
   15     '----------
   16     ''' <summary>
   17     ''' Summary for Variable2
   18     ''' </summary>
   19     ''' <remarks>
   20     ''' Remarks for Variable2
   21     ''' </remarks>
   22     Dim Variable2 As Integer
   23     '----------
   24     ''' <summary>
   25     ''' Summary for Function1
   26     ''' </summary>
   27     ''' <param name="p1">Description of parameter p1</param>
   28     ''' <param name="p2">Description of parameter p2</param>
   29     ''' <returns>
   30     ''' Description of return value of Function1
   31     ''' </returns>
   32     ''' <remarks>Remarks for Function1</remarks>
   33     Function Function1(ByVal p1 As Integer, _
   34         ByVal p2 As Char) As String
   35         Function1 = Nothing
   36     End Function
   37     '----------
   38     ''' <summary>
   39     ''' Summary for Function2
   40     ''' </summary>
   41     ''' <param name="p3">Description of parameter p3</param>
   42     ''' <param name="p4">Description of parameter p4</param>
   43     ''' <param name="p5">Description of parameter p5</param>
   44     ''' <returns>
   45     ''' Description of return value of Function2
   46     ''' </returns>
   47     ''' <remarks>Remarks for Function2</remarks>
   48     Function Function2(ByVal p3 As Integer, _
   49         ByVal p4 As Char, ByVal p5 As Single) As Double
   50         Function2 = Nothing
   51     End Function
   52 End 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:

    1 <?xml version="1.0"?>
    2 <doc>
    3 <assembly>
    4 <name>
    5 WebApplication3
    6 </name>
    7 </assembly>
    8 <members>
    9 <member name="F:WebApplication3.Class1.Variable1">
   10   <summary>
   11  Summary for Variable1
   12  </summary>
   13   <remarks>
   14  Remarks for Variable1
   15  </remarks>
   16 </member><member name="F:WebApplication3.Class1.Variable2">
   17   <summary>
   18  Summary for Variable2
   19  </summary>
   20   <remarks>
   21  Remarks for Variable2
   22  </remarks>
   23 </member><member 
name="M:WebApplication3.Class1.Function1(System.Int32,System.Char)">
   24   <summary>
   25  Summary for Function1
   26  </summary>
   27   <param name="p1">Description of parameter p1</param>
   28   <param name="p2">Description of parameter p2</param>
   29   <returns>Description of return value of Function1</returns>
   30   <remarks>Remarks for Function1</remarks>
   31 </member><member name=
"M:WebApplication3.Class1.Function2(System.Int32,System.Char,System.Single)">
   32   <summary>
   33  Summary for Function2
   34  </summary>
   35   <param name="p3">Description of parameter p3</param>
   36   <param name="p4">Description of parameter p4</param>
   37   <param name="p5">Description of parameter p5</param>
   38   <returns>Description of return value of Function2</returns>
   39   <remarks>Remarks for Function2</remarks>
   40 </member><member name="T:WebApplication3.Class1">
   41   <summary>
   42  Summary for Class1
   43  </summary>
   44   <remarks>
   45  Remarks for Class1
   46  </remarks>
   47 </member>
   48 </members>
   49 </doc>

 

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 documentation

Now 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:

 

Figure 1

 

Figure 2

 

Figure 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

  • [1] Microsoft Visual Studio 2005 Update to Support Web Application Projects can be found here.
  • [2] Visual Studio 2005 Web Application Projects add-in can be found here.
  • [3] The development website of NDOC can be found here. Unfortunately the latest version of NDOC on this website does not support .NET framework 2.0, only 1 and 1.1 are supported.
  • [4] A version of NDOC that supports .NET framework 2.0 can be found here.
  • Refer to the online copy of Microsoft Developers Network at http://msdn.microsoft.com or use your own local copy of MSDN.

Tutorial toolbar:  Tell A Friend  |  Add to favorites  |  Feedback  |   


comments powered by Disqus