Parent issue: #19807
Coverage table
Writing API Specifications
Chapter link
Content
Image
Text
Writing API Specifications
Ideally, the Java API Specification comprises all assertions required to do a clean-room implementation of the Java Platform for "write once, run anywhere" such that any Java applet or application will run the same on any implementation. This may include assertions in the doc comments plus those in any architectural and functional specifications, usually written in FrameMaker, or in any other document. This definition is a lofty goal and there is some practical limitation to how fully we can specify the API. The following are guiding principles we try to follow:
- The Java Platform API Specification is defined by the documentation comments in the source code and any documents marked as specifications reachable from those comments.
Notice that the specification does not need to be entirely contained in doc comments. In particular, specifications that are lengthy are sometimes best formatted in a separate file and linked to from a doc comment.
- The Java Platform API Specification is a contract between callers and implementations.
The Specification describes all aspects of the behavior of each method on which a caller can rely. It does not describe implementation details, such as whether the method is native or synchronized. The specification should describe textually the thread-safety guarantees provided by a given object. In the absence of explicit indication to the contrary, all objects are assumed to be "thread-safe", that is, it is permissible for multiple threads to access them concurrently. It is recognized that current specifications don't always live up to this ideal.
- Unless otherwise noted, the Java API Specification assertions need to be implementation-independent. Exceptions must be set apart and prominently marked as such.
We have guidelines for how to prominently document implementation differences.
- The Java API Specification should contain assertions sufficient to enable Software Quality Assurance to write complete Java Compatibility Kit (JCK) tests.
This means that the doc comments must satisfy the needs of the conformance testing by SQA. The comments should not document bugs or how an implementation that is currently out of spec happens to work.
Guidelines
This chapter does not appear to contain any guidelines. Proposal:
| Documentation Comments Rule |
Checkstyle Checks Used |
Sample files |
| Writing API Specifications |
-- |
|
| Separate Specification Documents |
-- |
|
| Contract Between Callers and Implementations |
-- |
|
| Implementation-Independent Assertions |
-- |
|
| Conformance Testing Requirements |
-- |
|
Parent issue: #19807
Coverage table
Writing API Specifications
Chapter link
Content
Image
Text
Writing API Specifications
Ideally, the Java API Specification comprises all assertions required to do a clean-room implementation of the Java Platform for "write once, run anywhere" such that any Java applet or application will run the same on any implementation. This may include assertions in the doc comments plus those in any architectural and functional specifications, usually written in FrameMaker, or in any other document. This definition is a lofty goal and there is some practical limitation to how fully we can specify the API. The following are guiding principles we try to follow:
Notice that the specification does not need to be entirely contained in doc comments. In particular, specifications that are lengthy are sometimes best formatted in a separate file and linked to from a doc comment.
The Specification describes all aspects of the behavior of each method on which a caller can rely. It does not describe implementation details, such as whether the method is native or synchronized. The specification should describe textually the thread-safety guarantees provided by a given object. In the absence of explicit indication to the contrary, all objects are assumed to be "thread-safe", that is, it is permissible for multiple threads to access them concurrently. It is recognized that current specifications don't always live up to this ideal.
We have guidelines for how to prominently document implementation differences.
This means that the doc comments must satisfy the needs of the conformance testing by SQA. The comments should not document bugs or how an implementation that is currently out of spec happens to work.
Guidelines
This chapter does not appear to contain any guidelines. Proposal: