This article describes the ASP Documentation Tool™, a utility I wrote to automate the documentation of web applications developed using ASP 2.0 or 3.0 and the VBScript and JScript scripting languages.

When developing applications using Java and Perl, I've always been impressed with the JavaDoc and PerlDoc documentation utilities these languages support. When producing work for a client, these utilities take a lot of the hard work out of the mundane (but critically important) work involved with documenting the project.

Unfortunately there is no such standard documentation utility for ASP, and having not found a suitable commercial offering, I decided to write my own documentation utility for ASP. Since I often work on projects inherited from other developers, such a utility would be able to give a useful overview of the project without having to manually look through the ASP code. The utility would also (hopefully!) create much of the low level documentation required when handing over work to clients, saving valuable development time.

Figure 1. The ASP Documentation Tool™'s GUI. Click image for full sized version.

Features

The ASP Documentation Tool™ scans all the files of a web project, and outputs a report based on what it finds within the files. The report contains a list of the following:

• A summary of the project.
• Pages within the site (.asp, .asa and .inc - other file types may be added if required).
• Full source code for each page, with optional syntax highlighting.
• A list of VBScript functions in the site, showing where they are defined and used.
• A list of VBScript subroutines in the site, showing where they are defined and used.
• A list of JScript functions in the site, showing where they are defined and used.
• A list of client-side JavaScript functions in the site, showing where they are defined.
• A list of ActiveX objects, showing where they are instantiated.
• A list of VBScript constants.
• A list of HTML Forms and Form elements.
• A list of Request.QueryString, Request.Form and Request.ServerVariables used.
• A list of email addresses used in the site
• A list of ASP Application and Session variables used.
• Details of SQL Server 2000 user tables and stored procedures in database(s) associated with the project.
• Details of Microsoft Access tables and queries in database(s) associated with the project.

The report is produced in standard HTML [view sample], with an option to export the report in Microsoft's HTML Help  [view sample] and plain text format [view sample]. The HTML output can be viewed in any web browser on any operating system. By contrast, the HTML Help format is restricted to machines running Microsoft Windows. HTML Help does, however, have some useful advantages over the standard HTML output:

• The documentation is stored as a single .chm file, making it easier to redistribute.
• The documentation contains a useful table of contents showing an overview of the site.
• There is an index as well as a search facility.
• The search facility also allows full searching of the source code of each page in the documented website.

Figure 2. The HTML Help report compiled by the ASP Documentation Tool™ allows easy searching of the project documentation, including the ASP source code.