1. Writing Javadoc™ comments using XXE

Figure 1. A Java file as displayed by XXE

A Java file as displayed by XXE

The intended audience for this plug-in is Java™ programmers and Javadoc™ writers. With XXE and this plug-in, it becomes possible to edit the Javadoc comments contained in a Java file using a word processor-like view. Writing Javadoc this way is less tedious (no manual formatting of comment lines) and is no longer error-prone (DTD-directed editing).

This plug-in has full support for all Javadoc 1.4 tags (see Javadoc Home Page) plus most of HTML 3.2 tags.

The following HTML 3.2 tags and attributes are not supported:

The Javadoc 1.4 tags are modeled in XML as follows:

The file name extension required for a ``Javadoc document'' is .java.

Unlike Web browsers, this plug-in is not designed to load broken HTML 3.2. However, this plug-in can help Javadoc writers to easily spot and fix the HTML errors contained in Javadoc comments. See next section for a real world case study.

Figure 2. The Javadoc plug-in refuses to load Sun's Date.java

The Javadoc plug-in refuses to load Sun's Date.java

When XXE refuses to load a Java file, an error dialog is displayed with

Try to guess what the error message means and fix the problem using your favorite text editor, then reload the Java file into XXE.

For the above example, it is pretty easy to fix the problem:

    /**
     * Creates a string representation of this <tt>Date</tt> object of 
     * the form:
     * <blockquote<pre>
     * d mon yyyy hh:mm:ss GMT</pre></blockquote>

1.1. Applying the Javadoc plug-in to Sun JDK 1.3.1 sources

The Javadoc plug-in has been tested on all the Java sources given by Sun for the Linux JDK 1.3.1.

The plug-in has succeeded to load 1750 out of 1877 Java files. It has failed 127 times generally for the following reasons:

  • The Javadoc writer adds <code></code> tags at places where plain text (#PCDATA) is expected.

    Example: putting the name of a @param between <code></code>.

    Note that it is not useful to do so because Javadoc automatically adds a sensible style to this kind of plain text.

    This is the most important discrepancy between the Javadoc plug-in and Javadoc: Javadoc intelligently discards <code></code>, while the Javadoc plug-in stubbornly refuses to load the Java file.

  • Typos such as:

    • typos in tag names (examples: blockquoute, coder)

    • forgetting '>' at the end of start or end tags

    • unknown character entities (example: &le;)

    • putting a space between the attribute name, the '=' sign and the attribute value

    • using end tags (example: </p>) instead of start tags

    • duplicating attributes (example: align)

  • The Javadoc comments writer sometimes forgets what he has learned about HTML.

    Example 1: putting plain text or inline elements such as <code></code> directly into a blockquote.

    Example 2: putting a pre block between <code></code>.

  • '>', '<', '&' not properly escaped. Here, the plug-in tries to do its best but sometimes it misses some of these special characters.

Note that all the errors described above are impossible to do if XXE is used to edit the Javadoc comments.

Having succeeded to load a Java file into XXE does not mean that this file is valid: 45 out the 1750 loaded files were found having validity problems.

Generally these validity problems are minor and are caused by missing attributes or invalid attribute values. It is possible to quickly fix them by using menu command Tools|Check Validity.