Summary

Enhance @return tag to address common situations with duplicated text.

Problem

For many simple methods, the doc comment is of the form:

/**
 * Returns the result. Additional text.
 * ...
 * @return the result

This involves unnecessarily duplicated text.

Solution

Enhance the existing @return tag to be usable as an inline tag, such that it can provide a default for an equivalent block tag. Continuing the previous example, the comment can be simplified to:

/**
 * {@return the result} Additional text.
 * ...

Specification

The inline variant of the tag can only be used as the first tag in the comment, and stands in for the first sentence. A warning is generated if it is used elsewhere. As with the existing block tag, a warning is given if the content of the tag is empty.

The expansion of the inline variant of the tag is:

Returns {0}.

where {0} is replaced by the contents of the inline tag. The contents may contain inline tags and HTML markup, the same as for the block variant.

The inline variant of the tag provides a default equivalent block tag when searching for such a tag: this includes when searching for an inherited tag.

Compiler Tree API

The change requires some corresponding changes in the Compiler Tree API (com.sun.source.*)

1. ReturnTree is modified to implement InlineTagTree as well as BlockTagTree.
2. A new method boolean isInline() is added to ReturnTree, to determine the form of the instance of the source code.
3. A corresponding new method is added to the DocTreeFactory class, to be able to specify the form of the instance for a ReturnTree.

A diff of the proposed API changes is attached. (It does not appear to be possible to include the diffs inline here.)