| home / experts / xml / column64 |
|
|
|
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 < 0) || (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:
A tool for documenting DTDs is dtd2html.
Produced by Michael Claßen
Legal Notices, Licensing, Reprints, Permissions, Privacy Policy.
Advertise | Newsletters | Shopping | E-mail Offers | Freelance Jobs 
URL: http://www.webreference.com/xml/column64/index.html
Created: Sep 16, 2002
Revised: Sep 16, 2002
