Bibliography
Implementation and other Engineering Considerations
Documentation Quality
Java offers a standard way of creating code-level documentation using the javadoc utility. All the APIs--including the Java core APIs--are documented in this fashion. The Javadoc tool is part of the Java SDK, standard edition. Provided that the two following rules are respected, the utility will generate a set of HTML pages, organised hierarchically--laid out consistently with the core Java API documentation from Sun. First Javadoc comments must be enclosed in /** ... */, rather than in the ``C-style'' /* ... */. Then comments must be positioned immediately above the declaration of the elements of the language (classes, methods, fields) they describe. The javadoc utility will then be able to obtain semantic information from the comments and relate it to the syntactic information extracted from the main java code.
This approach is conceptually close to Knuth's Literate Programming initiative (see (Knuth, 1984)). If software is more often than non considered to be poorly documented--Javadoc can help by providing a means to create consistent-looking, API-level documentation (i.e. the appropriate level of abstraction for the typical use of a middleware framework like XMLbroker)--with a small overhead for the programmer.
Figure 5.1 represents the documentation for the Message class. In the current version of Javadoc, comments are written in HTML, which unfortunately does introduce a strong inter-dependency between the content and the presentation-specific information.
Bibliography
Implementation and other Engineering Considerations
Documentation Quality
