Background for
Writing Java API Specifications
There has been much discussion about what is and is not a specification for
each of the JavaTM platform API
libraries. It has been decided
that the Javadoc comments, with additional supporting documentation as
necessary, will make up the specification for each Java platform API library.
Audience
There are four distinct audiences for the API specification:
- Sophisticated Java platform developers who need a complete reference
- Clean room implementors of a given Java platform
- Java platform licensees
- Conformance test developers
The primary audience is sophisticated Java platform developers, however
there is enough overlap in content requirements that all audiences should
obtain adequate information.
Conformance Test Need for Specs
In general, the requirements for a Java platform API specification are
accuracy and completeness. Conformance testing adds an additional
requirement: timeliness. Unlike product testing, which can begin as soon as
some part of the program is written, conformance testing requires both a
working implementation and an accurate, complete specification before test
development can begin. This document attempts to define what "complete" means
for Java platform API specifications.
Kevin A. Smith and Doug Kramer
Last modified: Tue Sep 28 11:24:36 PDT 1999