This document describes the requirements for writing API specifications for the Java platform. The specification for each Java TM platform API library is made up of its Javadoc comments and additional support documentation called out in the doc comments.
This document has five sections that correspond to the sections of an API specification; each section (except the first) includes examples.
How to Write Doc Comments for Javadoc
Note: Examples have been modified to demonstrate completeness. They may not be completely accurate.
Assertions are critical to conformance testing and implementors of the Java Platform. The Java Compatibility Kit includes a test to verify each assertion, to determine what passes as Java Compatible TM .
The top-level specification is composed of those specifications that apply to the entire set of packages. It can include assumptions that underlie the other specifications, such as all objects are presumed to be thread-safe unless otherwise specified.
In addition to the class specific requirements, there are overall Java platform API documentation requirements with respect to handling unchecked exceptions (exceptions that derive from java.lang.RuntimeException). It would be helpful to develop some blanket statements that describe the general situations when a Java application should be prepared to encounter one or more RuntimeExceptions.
The Package specification includes any specifications that apply to the package as a whole or to groups of classes in the package. It must include:
For details about how to actually structure the package information in the
package.html file according to Java Software standards, see Package-Level Comments.
This example demonstrates the Executive Summary (first 3 paragraphs) and OS/Hardware Dependencies (fourth paragraph).
Contains classes for creating user interfaces and for painting graphics and images. A user interface object such as a button or a scrollbar is called, in AWT terminology, a component. The Component class is the root of all AWT components. See Component for a detailed description of properties that all AWT components share.
Some components fire events when a user interacts with the components. The AWTEvent class and its subclasses are used to represent the events that AWT components can fire. See AWTEvent for a description of the AWT event model.
A container is a component that can contain components and other containers. A container can also have a layout manager that controls the visual placement of components in the container. The AWT package contains several layout manager classes and an interface for building your own layout manager. See Container and LayoutManager for more information.
Behavior of user interface components may be restricted by the underlying operating system. For example, Windows does not allow simultaneously displaying the caret position and selection highlight, while Solaris does. That is, in Windows, applying the
setCaretPosition method to a text area causes any highlighted text to become unhighlighted, but in Solaris that method does not disturb a highlight.
This example demonstrates the Executive Summary (first section) and References to External Specifications (second section). (This second section contains links to the documents published on the Internet.) Notice that the references are specific down to the version number.
Package java.util.zip Description
Provides classes for reading and writing the standard ZIP and GZIP file formats. Also includes classes for compressing and decompressing data using the DEFLATE compression algorithm, which is used by the ZIP and GZIP file formats. Additionally, there are utility classes for computing the CRC-32 and Adler-32 checksums of arbitrary input streams.
The following external documents are part of the specification:
This section applies to Java classes and interfaces. Each class and interface specification must include:
writeObjectmethods, the fields that are serialized, the data types of those fields, and the order those fields are serialized. See example.
You may include graphic model diagrams, such as state diagrams, to describe static and dynamic information about objects. Such diagrams may become a requirement in the future. Code examples are useful and illustrative.
This example demonstrates the Executive Summary (first paragraph). The following paragraphs provide more detail and special cases for the specification.
A collection that contains no duplicate elements. More formally, sets contain no pair of elements
The additional stipulation on constructors is, not surprisingly, that all constructors must create a set that contains no duplicate elements (as defined above).
Note: Great care must be exercised if mutable objects are used as set elements. The behavior of a set is not specified if the value of an object is changed in a manner that affects
This example demonstrates the Executive Summary (first paragraph), State Information (second paragraph), OS/Hardware Dependencies (third paragraph), Allowed Implementation Variance (third paragraph) and Security Constraints (fourth paragraph).
A file output stream is an output stream for writing byte data to a
In addition, the ability to create or write to a file or file descriptor may be constrained by a Security Manager. This means that the constructors may throw
( Example to come)
Each field specification must include:
null, and how this object will behave in such a case. See example.
These four examples of fields demonstrate What this field models (first sentence) and Valid range of values (second sentence). They do not need to specify null value, since they are primitive types.
The x coordinate of one corner of this rectangle. Negative values are allowed for this field.
The y coordinate of one corner of this rectangle. Negative values are allowed for this field.
The width of this rectangle. When width is less than zero, Rectangle behavior is undefined.
The behavior of the following methods is undefined when either width or height is less than zero:
The height of this rectangle. Rectangle behavior is undefined when height is less than zero.
This example demonstrates What this field models (first paragraph) and Null value (second paragraph). This field is not constrained to a range of values.
The underlying input stream. Calls to
This value may be
This section applies to Java methods and constructors. Each method and constructor specification must include:
nullis passed in. See two examples. NOTE: If possible, document the general null argument behavior at the package or class level, such as causing a
java.lang.NullPointerExceptionto be thrown. Deviations from this behavior can then be documented at the method level.
null. See example.
AccessController.doPrivilegedconstruct. Also must include a general description of the context or situations where this method may be security constrained. See example.
This example demonstrates the Expected Behavior, State Transitions (first paragraph) and Cause of Exceptions (second and following paragraphs).
Sets the bit specified by the index to
If the index is less than zero, an
This example demonstrates the Expected behavior and Range of Valid Argument Values.
Returns the blue component in the range 0-255 in the default sRGB space.
the blue component.
This example demonstrates Null Argument Values, how
null can be a valid argument value.
This example demonstrates Null Argument Values and Cause of Exceptions. It shows how a
NullPointerException can be thrown when
null is passed in.
Returns the double value represented by the specified
the double value represented by the string argument.
This example demonstrates Range of Return Values. In this case, the specification constrains the return value to be non-negative, which adds information to what you could tell by its type alone (
int). Note that it is not necessary to state the max is
Integer.MAX_VALUE, since that is understood to be true for all
Returns the "logical size" of this
the non-negative logical size of this
This example demonstrates Algorithms Defined.
Returns a hashcode for this string. The hashcode for a
a hash code value for this object.
This example demonstrates OS/Hardware Dependencies, Allowed Implementation Variances, and Cause of Exceptions.
Writes the specified byte to this file output stream. Implements the
The behavior while the stream is open and available for writing may differ by platform and by implementation. Since the byte may be buffered either by the Java implementation or by the underlying operating system, this byte might not be immediately written to disk. Therefore, errors writing to the file or file descriptor might only be exposed when flushing or closing the stream.
This example demonstrates Security Constraints and Cause of Exceptions.
Creates an output file stream to write to the file with the specified name.
if the file could not be opened for writing.
if write access to the named file is not allowed. If a security manager exists, this method calls the security manager
1This document is based on the Object Class Specification by Edward V. Berard, Essays on Object-Oriented Software Engineering, 1993 Simon & Schuster, Englewood Cliffs, NJ; pp. 131-162.
Kevin A. Smith and Doug Kramer
Last Updated: January 2003.