Documenting DTDs I: dtd2html (1/2) - exploring XML

Documenting DTDs I: dtd2html

Documenting one's deeds is usually not high priority for developers, and Web developers are no exception. But alas, once you have to look again at stuff you've done weeks or months ago, the usefulness of documentation becomes apparent.

While not many of us write document type definitions (DTDs), or their heir formats XML schema and RELAX NG, we all have to get our head around one or the other DTDs at some point. Even if we've used some of them for ages, we might not have made appropriate use of some of their features. By the way, do you happen to know the xmp tag in HTML?

Most schemas today are described in prose, in various document formats such as XML, HTML or PDF. Little standardization has taken place in this area. Even at a big DTD-inventing organization like the Web Consortium (W3C) different authors have slightly varying styles of presentation and formatting of DTD summaries.

In contrast, the Java programming language came from day one with a highly popular tool for generating HTML documentation from Java code: javadoc. It is good, standard practice for Java developers to augment their code with javadoc comments. Classes, fields and methods can be prefixed with special comments in a particular format using certain keywords. The javadoc tool can then automatically recognize these comments, and use them to generate HTML documentation for the items they refer to.

The code that constitutes the Java platform itself has been documented in this way as well, providing a great additional source of information for the Java developer coding against various parts of the Java runtime.

Let's look at an example from java.lang.String, the Java String class:

class String {
...
    /**
     * Returns the character at the specified index. An index ranges
     * from <code>0</code> to <code>length() - 1</code>. The first character 
     * of the sequence is at index <code>0</code>, the next at index 
     * <code>1</code>, and so on, as for array indexing.
     *
     * @param      index   the index of the character.
     * @return     the character at the specified index of this string.
     *             The first character is at index <code>0</code>.
     * @exception  IndexOutOfBoundsException  if the <code>index</code> 
     *             argument is negative or not less than the length of this 
     *             string.
     */
    public char charAt(int index) {
	if ((index = count)) {
	    throw new StringIndexOutOfBoundsException(index);
	}
	return value[index + offset];
    }
...
}
    

The text block behind asterisks will be copied into the documentation HTML, and the special markers @params, @return and @exception will be appropriately formatted as method parameters, return value, and thrown exceptions.

This approach is highly beneficial for a number of reasons:

• Standardized: Every developer is familiar with reading and writing this format, as well as the generated results.
• Expected: Developers are expected to write comments alongside the code.
• (Semi-)automatic: Tools are available to manipulate and extract the documentation.

A tool for documenting DTDs is dtd2html.

Produced by Michael Claßen

URL: https://www.webreference.com/xml/column64/index.html
Created: Sep 16, 2002
Revised: Sep 16, 2002