|
|
The Transglobal Web Based Application (WBA) automated code documentor was developped for application to WBA code files used at Transglobal Express Ltd. The primary objective was to provide a means for automatically producing documentation for WBAs where no such documentation prviously existed. The basic concept and mode of operation is based on the Java Doc Tool produced ny Sun Microsystems, i.e. the documentor makes use of specially annotated commnets in the source code. The documentor was developed as part of the Transglobal KTP project; a joint venture between Transglobal Express Ltd and the Department of Computer Science at University of Liverpool.
Broadly the documentor identifies .asp and script blocks within WBA code files and then the functions within those blocks. Once identified information is extracted and displayed in a series of .html files (one per code file making up the WBA). The naming convention for the "document files" is to remove amy post fix (e.g. .asp or .html) and replace it with Doc.html. The documentation files are currently written to the same directory from which the documentation generator code is run.
Much of the information extracted is based on comments within the code, the onus is on the developers to include these comments. Alternatively the maintenance team can include appropriate comments, this is the approach that has been used at Transglobal Express for the purpose of reverse engineering WBA code.
In more detail the following code elements are identified:
Each is discussed in further detail in the following sections.
Tge documentor code includes both a GUI and command line interface. In the case of the command line interface the list of WBA source code files to be documented must be hard coded into the application class (ASPdocApp.jaVA) by the user (remember to recompile). The GUI interface is more versatile. The nature of the output (links, ASP blocks, ASP functions, Script blocks and Script functions) is fixed in the case of the command line interface. HGowever, output can be influenced by the user in the case of the GUI. (Acctually output can also be influenced in the case of the command line interface but this requires editting of the code.)
|
The start material is considered to comprise a title and/or an opening comment.
The title, if present, is assumed to be contained between the <title> and </title> HTML tags. Note that the title tags may be located anywhere in the code file. Note also that where there are more than one pair of title tags the first pair arrived at will be selected.
The opening comment is considered to exist either:
Note that if there is no opening body tag there may still be an opening comment on the first or second lines respectively (regardles of whether a title has been found as the tile may be contained later in the code file). The opening comments can go on for several lines. The comment is always assumed to be in the form of an HTML comment, i.e.:
<! Some example text to represent a
comment going over two lines.>
|
Hyperlinks are identified by looking for opening <A HREF HTML tags. The URL is expected to be contained between the associated = and > characters, with or without quotes. Examples:
<A HREF = "anExampleLink.html">
<A HREF = "#anotherLink">
<A HREF = YetAnother/exampleLink.html>
|
ASP code blocks are identified by <% and %> tags. The start and end line numbers are identified and any opening comments found immediately after the start line. ASP comments are of the form:
' Some example text to represent a
' comment going over two lines.
|
ASP functions are assumed to have the format function name ... end function or function name (args) ... end function. The start and end line numbers are recorded together with the function name and any arguments. An explanatory comment, if included, is assumed to be located immediately before the start of the function (white space excepted) which is also extracted (if available).
|
Script blocks are identified by <SCRIPT> and </SCRIPT> tags. The <SCRIPT> is assumed to be located at the beginning of a line. The start and end line numbers are identified and any opening comments found immediately before the start line (white space excepted). The nature of the scrript is determined from the LANGUAGE or TYPE script argument. Examples:
<SCRIPT TYPE="text/JavaScript">
<SCRIPT LANGUAGE="VBScript">
|
Currently script functions are assumed to be written in either VBScript or JavaScript. For each function the start and end line numbers are recorded together with the function name, any arguments and a preceding comment if it exists. Functions have the form:
| Java Script | VB script |
FUNCTION name
...
END FUNCTION
|
FUNCTION name {
...
}
|
FUNCTION name(args)
...
END FUNCTION
|
FUNCTION name(args) {
...
}
|
Preceding comments are of the form:
' Some example text to represent a VBScrtipt comment.
in VBScript, or:
/* Some example text to represent a Java Scrtipt comment. */
in JavaScript.
|
The software is written in Java and comprises the following (note that there are two application classes):
The code is compiled in the usual way:
javac *.java
and run using either the command line interface:
java ASPdocApp
or the GUI interface:
java ASPdocApp_GUI
To document the Java source code use:
javadoc -private -d temp *.java
|
Produced as part of the Transglobal Express KTP project.