|
ASP Kitchen: ASP.NET Articles: An ASP.NET
Documentation Tool
An ASP.NET Documentation Tool
This article describes the ASP.NET Documentation Tool, a utility I wrote to automate the
documentation of ASP.NET 1.0, 1.0 and 2.0 web applications written in VB.NET or C#.
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. Following the success of
the ASP Documentation Tool which I released in May
2002, I decided to release a ASP.NET version. Microsoft have made tentative steps in
allowing the automatic documentation of ASP.NET projects, but only if they are written in
C#. The ASP.NET Documentation Tool creates documentation for both VB.NET and C#.
Features
The ASP.NET Documentation Tool scans all the following files of a web project, and
outputs a report based on what it finds within the files:
- ASP.NET file parser extracts content from files written in either VB.NET or C#.
Supported file types are:
- ASP.NET files (.aspx, .asax).
- User Controls (.ascx).
- Code Behind Files containing the code associated with ASP.NET files and User Controls.
- Custom components (.vb and .cs).
- Web.config files.
The report contains a list of the following:
- For both VB.NET and C#:
- Namespaces: What namespaces are in the project, and which classes are in each namespace.
- Classes: What classes are in the project, which namespace they belong to and what
functions and subroutines are defined within each class.
- Functions: Where they are defined, and which arguments they use.
- Subroutines: Where they are defined, and which arguments they use.
- Where Application and Session variables are used.
- Which User Controls are used in the project.
- Which Web Controls are used in the project.
- Which Validation Controls are used in the project.
- What web.config files are used on the project.
- SQL Server 7 2000 and 2005 databases associated with the ASP.NET project can also be
documented, with the following features:
- Shows a list of tables within the database.
- Shows a list of views within the database.
- Shows a list of column names, type and length associated with each table.
- Shows a list of stored procedures, including the full text of each stored procedure and
its input parameters.
- There are a number of output options:
- Standard HTML: This can be viewed in any web browser [view sample], including Internet Explorer and Netscape.
- Microsoft's HTML Help format. This format [view sample] has the advantages of:
- The project documentation is contained within a single, compressed .chm file.
- The project documentation is searchable.
- There is an index of project items.
- The project documentation can be further modified using Microsoft's freely available
HTML Help Workshop application.
- Plain Text: This is a text file containing a summary of the project [view sample]. As such it can be used as the basis of custom
documentation written in a word processor.
- The HTML format reports contain full copies of all files which have the following
features:
- Optional color coding and syntax highlighting of source code, making it easier to read.
- Optional line numbering of source code.
- There is the option to either colour code or hyperlink all of the following in the
source code:
- User Control usage.
- Web Control usage.
- Validation Control usage.
- Application and Session variable usage.
- C# and VB.NET Functions and Subroutines.
System Requirements
The ASP.NET Documentation Tool can be used on a machine running Microsoft Windows 95 or
any subsequent version of Windows. Windows NT 4.0 or Windows 2000 is recommended. The .NET
Framework is not required.
The ASP.NET Documentation Tool is able to save project
documentation in Microsoft's HTML Help format. To be able to do this then Microsoft's HTML
Help Workshop must be installed. This is a free
download from Microsoft.com.
Configuring and Running the ASP.NET Documentation Tool
The ASP.NET Documentation Tool has a single command line option which specifies the
filename of the configuration file. So to create documentation for the Sample ASP.NET
project supplied, the following is typed at the command prompt (or run from a .bat file):
ASPNETDocumentationTool.exe --c="Config.ini"
There is also a full Graphical User Interface!
The configuration file [view sample] is a plain text file containing the configuration
options.
The ASP.NET Documentation Tool can of course be scheduled to automatically update
project documentation by making use of the Windows AT command or the Task Scheduler.
The ASP.NET Documentation Tool creates a log file in plain text format [view sample].
Obtaining the ASP.NET Documentation Tool
The evaluation version of the ASP Documentation Tool is available here:
The full version of the ASP.NET Documentation Tool is available for online purchase. Purchasing the ASP.NET Documentation Tool allows you
to download the current version, and all subsequent versions released up to 18 months
from the date of purchase. Specially
discounted offers are also available when purchasing the ASP Documentation Tool, SQL Documentation Tool or Index Server Companion at the same time.
Comments/Suggestions?
I've released the ASP.NET Documentation Tool in the hope that other users may find it
useful! I'd love to hear what you think of it. Is it useful? What new features do you
want? What should I add next?
Downloads
Further reading
- Read about the ASP Documentation Tool, which
creates documentation for ASP 2.0 and 3.0 sites written in VBScript or JScript.
- ASP
Documentation Systems. A look at commercial classic ASP Documentation Systems, and how
to go about creating your own system.
Useful Development Tools
| ASP
Documentation Tool™ |
| Automatically creates technical documentation for ASP 2.0
and 3.0 web applications written in VBScript and JScript. Documentation for Microsoft
Access, SQL Server 7/2000 databases and Visual Basic 6.0 components associated with the
web application can also be incorporated into the reports. Documentation is created in
HTML, HTML Help and plain text formats. |
 View Sample
Output (HTML Help format).
 View Sample Output (HTML Format).
 Download
Trial Version (5.2Mb ZIP file). |
| .NET Documentation Tool |
| Automatically creates technical documentation for .NET Framework applications written in C# or VB.NET (including ASP.NET).
Documentation for SQL Server 7/2000/2005 databases and C#/VB.NET components associated with the
web application can also be incorporated into the reports. Documentation is created in
HTML, HTML Help and plain text formats. Additional support for ASP.NET web applications. A useful alternative to NDoc! |
View Sample
Output (HTML Help format).
View Sample Output (HTML Format).
Download
Trial Version (3Mb ZIP file). |
| SQL
Documentation Tool |
| The SQL Documentation Tool creates technical documentation for Microsoft SQL Server 7.0, 2000 and 2005 databases. Technical documentation is created in HTML and HTML Help formats. The HTML Help format documentation is fully searchable and cross referenced. The SQL Documentation Tool documents SQL Server Tables, Views, Stored Procedures, Triggers, Table Relationships, Jobs and DTS Packages. |
View Sample
Output (HTML Help format).
View Sample Output (HTML Format).
Download
Trial Version (10.3Mb ZIP file). |
| Text Workbench |
| Text Workbench is a file search and replacement utility for text files and Microsoft Office documents. Make rapid file replacements on multiple files and folders full of files. Advanced replacement options include regular expressions support. It even works on remote file systems via FTP. A Regular Expression Laboratory allows advanced pattern matching and replacement expressions to be built and tested. This great utility will make your everyday development tasks much easier!
|
|
Download
Trial Version (3Mb ZIP file; you have the option to either install directly from this link or save the file for later installation). |
| ASP Spell Check |
| ASPSpellCheck is the easy way to add spell checking capabilities to your ASP or ASP.NET websites, Intranets and web applications. The utility allows you to add spell checking capabilities to any HTML text field or rich content editing text box. It works with all common web browsers, and there are no components or databases to install on the server.
|
Read ASPSpellCheck Review.
View ASPSpellCheck Examples.
Download
Trial Version (3Mb ZIP file; you have the option to either install directly from this link or save the file for later installation). |
Author details
Brett Burridge
has worked as a web developer since 1997 and has developed web applications for a range of corporations, start up busiensses and educational establishments.
Brett is presently employed as an Internet developer and technical writer
through his own company,
Winnersh Triangle Web Solutions Limited.
The company produces a number of
innovative products, including a range of software documentation tools, which include the
ASP Documentation Tool™, the .NET Documentation Tool for VB.NET and C#, and the SQL Server Documentation Tool. Other products include The Website Utility, which functions as a website error checker, search engine optimizer and ASP/ASP.NET search engine builder application.
As well as the ASPAlliance, Brett has written articles for Ariadne.ac.uk,
ASPToday, the software documentation portal www.softwaredocumentation.info, and has contributed recipes to the ASP.NET Developer's Cookbook.
links
Outside web development, Brett is interested in travelling (here are my travel logs from New York, Hong Kong and Tokyo), digital photography (here's my photo gallery), tropical fishkeeping
and collecting contemporary works of art by artists such as Doug Hyde.
Contact Brett by emailing
Article history
"An ASP.NET Documentation Tool" published on ASPAlliance.com on 01 December
2002, last revised 30 April 2003.
ASP Kitchen: ASP.NET Articles: An ASP.NET
Documentation Tool
|
|
