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.

System Requirements

The ASP Documentation Tool™ is written in Perl 5, but has been compiled into a Windows executable file that can be used on any machine without requiring Perl.

If you want the ASP Documentation Tool™ to create a report in HTML Help format then you will need to download and install the HTML Help Workshop. This is a free download from Microsoft.com. It is strongly recommended that you install the HTML Help Workshop to the default location, which is C:\Program Files\HTML Help Workshop. If the HTML Help Workshop is installed elsewhere then the ASP Documentation Tool™ will need to be modified to change the value of the variable called "HTMLHelpProg".

Configuring and Running the ASP Documentation Tool™

The ASP Documentation Tool™ is installed using a standard Windows installation routine. There is a graphical user interface - The ASP Documentation Tool™ Configurator - for configuring documentation jobs.

The ASP Documentation Tool™ executable file must be supplied with several command line options which control the behaviour of the script and the appearance of the output report. There are just two mandatory command line options, which are used to specify the input folder (i.e. the folder containing the ASP files that are to be documented) and the output folder (i.e. where the report should be placed).

Option	What it does	Example
--i	Input folder containing the website's files. Use a vertical bar to specify more than one input folder (useful if your includes are in a separate location).	"C:\inetpub\wwwroot\mywebsite", or "C:\Inetpub\wwwroot\SampleWeb|C:\Inetpub\wwwroot\includes"
--o	Output folder where the report should be placed	"D:\reports\mywebsite"

So the following command when typed in the folder in which the ASPDocumentationTool.exe resides would document the web project in C:\inetpub\wwwroot\mywebsite and output the report in the folder D:\reports\mywebsite:

ASPDocumentationTool.exe --i="C:\inetpub\wwwroot\mywebsite" --o="D:\reports\mywebsite"

Note that the script will overwrite a previous report in that folder.

The following command line options are optional:

Option	What it does	Example
--v	Verbose mode outputs script status to console.	0 or 1
--cs	Specifies whether the source code of ASP pages and SQL stored procedures should by color coded and syntax highlighted.	0 or 1
--h	Whether entities in the source code should be hyperlinked.	0 or 1
--c	Whether entities in the source code should be color coded.	0 or 1
--l	Whether the source code pages should display line numbers. 1 = numbering, 0 = no line numbering. Numbering is on by default. This is a useful option if you want to use the ASP Documentation Tool™ to create syntax highlighted ASP for publication purposes (like I do on my own ASPAlliance site!)	0 or 1
--txt	Whether the report should be exported as plain text format (using the filename "projectname".txt).	0 or 1
--dsn	Connection string allowing script to access a SQL Server 2000 database. At the very least this should contain the name of an ODBC data source, together with a SQL Server username and password.	"DSN=Northwind;UID=webuser;PWD=Htf674HHs"
--db	name of database to document. Use a vertical bar to specify more than one database.	"Northwind", or "Pubs|Northwind"
--hh	Whether the output should be compiled in HTML Help format.	0 or 1
--project	Specifies a name for the project.	"SampleWeb"

As an example, the ASP Documentation Tool™ could be called from the command line using:

ASPDocumentationTool.exe --i="C:\inetpub\wwwroot\mywebsite" --o="D:\reports\mywebsite" --cs=1 --v=0 --hh=1 --project="SampleWeb"

Don't forget that it is possible to run the ASP Documentation Tool™ on Windows machines from .bat scripts, which can of course be scheduled using the AT command or the Windows Task Scheduler.

The ASP Documentation Tool™ reports are created in standard HTML, which can be subsequently edited using any HTML editor. The HTML Help format output may also be edited by using Microsoft's HTML Help Workshop - the HTML Help Workshop project file is created in the output folder along with the rest of the report, and it has a .hhp file extension.

Figure 3. Microsoft's HTML Help Workshop can be used to modify the HTML Help report.

The ASP Documentation Tool™ creates a log file in plain text format [view sample].

• Download the ASP Documentation Tool™ 4.2 Evaluation Version (3.5 Mb ZIP file).

• Purchase the ASP Documentation Tool™ Full Version ($49.99).

The full version of the ASP Documentation Tool™ is available for online purchase from RegSoft from just $49.99. Purchasing the ASP Documentation Tool™ allows you to download the current version, and all subsequent versions released up to six months from the date of purchase.

Incidentally, an ASP.NET Documentation Tool is also available. This documents ASP.NET projects written in C# or VB.NET.