Date post: 2017-09-22 16:18
Note that it is always inappropriate to document that a method throws an unchecked exception that is tied to the current implementation of that method. In other words, document exceptions that are independent of the underlying implementation. For example, a method that takes an index and uses an array internally should not be documented to throw an ArrayIndexOutOfBoundsException , as another implementation could use a data structure other than an array internally. It is, however, generally appropriate to document that such a method throws an IndexOutOfBoundsException.
This document describes the style guide, tag and image conventions we use in documentation comments for Java programs written at Java Software, Oracle. It does not rehash related material covered elsewhere:
At Oracle, we have developed a tool for checking doc comments, called the Oracle Doc Check Doclet, or DocCheck. You run it on source code and it generates a report describing what style and tag errors the comments have, and recommends changes. We have tried to make its rules conform to the rules in this document.
With hierarchical file output, such as Javadoc , directories would be located in the package directory named doc-files. For example:
Returns an Image object that can then be painted on the screen. The url argument must specify an absolute URL. The name argument is a specifier that is relative to the url argument.
Thus, there are commonly two different ways to write doc comments -- as API specifications, or as programming guide documentation. These two targets are described in the following sections. A staff with generous resources can afford to blend both into the same documentation (properly chunked ) however, our priorities dictate that we give prime focus to writing API specifications in doc comments. This is why developers often need to turn to other documents, such as Java SE Technical Documentation and The Java Tutorials for programming guides.
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.
For example, if the members are acting as a unit—everyone doing the same thing at the same time—the collective noun is singular and requires singular verbs and pronouns. Read this example:
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.