JDK-8256804 : Add javadoc tag to avoid duplication of return information in simple situations.
  • Type: CSR
  • Component: tools
  • Sub-Component: javadoc(tool)
  • Priority: P4
  • Status: Closed
  • Resolution: Approved
  • Fix Versions: 16
  • Submitted: 2020-11-20
  • Updated: 2020-12-03
  • Resolved: 2020-11-24
Related Reports
CSR :  
JDK-8075778 - Add javadoc tag to avoid duplication of return information in simple situations.
Description
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.)_
Comments
The proposed fix will allow inline tags, like `{@code...}` within `{@return ...}`. We can (separately) look to extending that fix to other inline tags, like `{@summary ...}`. See https://github.com/openjdk/jdk/pull/1355/files#diff-873b8bd2b8ecd4acd77f5e500aa0ef469787e2e8976dd8bfc530c19465fcd9d0R167 File TestReturnTag.java Methods testInlineMarkup, testBlockMarkup Starting at line 167
03-12-2020
> Tags, like {@code} are not interpreted (acceptable) but HTML is accepted ... but with bugs: in my simple test case, white-space was lost, which is not really acceptable. I'll investigate. So inline `{@return}` will NOT interpret tags like `{@code}` or `{@link}`? Did I get that right? If so, then this new `{@return}` tag will not help in typical cases like these: /** * Returns {@code true} if this map contains a mapping for the specified * key. ... * @return {@code true} if this map contains a mapping for the specified * key ... */ boolean containsKey(Object key); and /** * Returns a {@link Method} corresponding to the given Java method declaration. * ... * @return a {@link Method} corresponding to the given Java method declaration. ... */ public static Method getMethod(final String method) { return getMethod(method, false); }
03-12-2020
> However, the form as proposed follows the form of other existing tags which can be used to provide the first sentence, such as {@summary ...} and {@inheritDoc}. Could you clarify that, Jon? What do you mean exactly when you say "follows the form of other existing tags"? To me, the similarity is superficial. One thing is that neither `@summary` nor `@inheritDoc` adds anything; whereas the proposed tag adds a period.
03-12-2020
There has been discussion that the usage should be `{@return <description>}.` with a period following the tag, because it looks "weird" without a period. However, the form as proposed follows the form of other existing tags which can be used to provide the first sentence, such as `{@summary ...}` and `{@inheritDoc}`.
03-12-2020
[~prappo] Typo: fixed. The inline variant performs the same as `{@summary}` which would be minimally acceptable were it not also buggy. Tags, like `{@code}` are not interpreted (acceptable) but HTML is accepted ... but with bugs: in my simple test case, white-space was lost, which is not really acceptable. I'll investigate. FWIW, the intent and expectation is that the content of the inline variant should be the same as that of the block variant, unless there is a really good reason for a difference.
03-12-2020
Moving to Approved. I had good experiences taking this feature out for a spin when developing an initial fix for JDK-8075778.
24-11-2020
[~prappo] I can fix the implementation so that we can specify that nested tags (like `{@code...}` and HTML are permitted inside `{@return ...}`. We can fix (opt-in) to the new behavior for `{@summary ...}` and other inline tags, but that should be done separately.
21-11-2020
> The inline variant of the tag can only be used as the first tag in the comment, and stands in for the first sentence. This is similar to `@summary`. Does the inline variant of `@return` allow any nested tags. Separately, what is the behavior in regards to special symbols such as `<`, `&`, and `@`? > instance for a returnTree. Typo: the leading *r* in `returnTree` should be capital.
20-11-2020