Package org.chwf.webdoc

A package with utilities to automate the generation of documentation for various types of files.

See:
Description

Class Summary

DTDDoc	A Java class for generating xdoc documentation from DTDs:
JavaScriptDoc	Utility class to generate Javadoc-style documentation for JavaScript.
TagDoc	A Java class with a main method for documenting tag library descriptors.
WebDoc	A Java class with a main method for documenting web applications XML descriptors.

Package org.chwf.webdoc Description

A package with utilities to automate the generation of documentation for various types of files. This includes DTDs, JSP custom tags, web.xml files and JavaScript.

It generates documentation using:

• Servlets: the web.xml file
• Tag libraries: the tag library descriptor (TLD).
• XML config: The DTD.

The reason for this approach is that these XML descriptors are the best place to document servlets and tags, since the descriptors contain critical information that is unavailable in the Java source files.

Web-doc requires the presence of a JAXP compliant XML parser to function. Both versions are executed as Java command line applications:

java org.chwf.webdoc.WebDoc [-d <target directory>] <path to web.xml>
java org.chwf.webdoc.TagDoc [-d <target directory>] <path to TLD file>
java org.chwf.webdoc.DTDDoc [-d <target directory>] <path to DTD file>

For example:

java org.chwf.webdoc.WebDoc -d docs conf/web.xml
java org.chwf.webdoc.TagDoc -d docs jutil.tld
java org.chwf.webdoc.DTDDoc -d docs dtds/config.dtd

For the web.xml file, the generated documentation is in the "webdoc.html" file. For tag libraries and DTDs, the generated documentation file has the same name as the config file with its file extension change to ".html". The web.xml, TLD and DTD can be written normally, with a few additional comments inserted in the correct places. A few descriptor tags that are "optional" in the Servlet/JSP standard are required for web-doc.

For web.xml:

• Both the web application and each servlet must have <display-name> and <description>.
• The <display-name> for the web application is assumed to be its context path.
• The <display-name> for each servlet is assumed to be its basic URL pattern, as understood by web developers. For example, a servlet with the URL pattern "/showItem/*" should have the display name "showItem".
• Though not strictly required, each servlet should include its expected request parameters at the end of its documentation.

For TLD:

• Both the tag library and each tag must have <info>.
• The <shortname> is assumed to be the tag prefix for the library.

Documentation comments are inserted as XML comments: <!-- Comment -->. The comment is associated with the element containing it. For example, in web.xml, comments inside the <web-app> tag are associated with the entire application. Comments inside each <servlet> tag are associated with that servlet. For TLD, comments under <taglib>, <tag> and <attribute> are associated with that element. Comments can include HTML markup as desired.