RFR: JDK-8075778: Add javadoc tag to avoid duplication of return information in simple situations. [v6]
Pavel Rappo
prappo at openjdk.java.net
Tue Dec 8 22:42:36 UTC 2020
On Tue, 8 Dec 2020 19:27:32 GMT, Jonathan Gibbons <jjg at openjdk.org> wrote:
>> src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/toolkit/taglets/ReturnTaglet.java line 76:
>>
>>> 74: } else {
>>> 75: List<? extends DocTree> firstSentence = utils.getFirstSentenceTrees(input.element);
>>> 76: if (firstSentence.size() == 1 && firstSentence.get(0).getKind() == DocTree.Kind.RETURN) {
>>
>> There's one more place where `firstSentence.size() == 1` is checked. I wonder if it could be a simpler `!firstSentence.isEmpty()` check?
>>
>> Are there any non-trivial cases which might bite us later, should we change that check?
>
> I think the code is better as is. It would be wrong to have a firstSentence containing multiple items, beginning with `{@return}` and then to only return the first one in the following line of code. Arguably, a better form may be to use `isEmpty()` and then subsequently assert (somehow) that the size is exactly 1, but using assertions like that is a different discussion (as you know!)
I guess I was thinking about a corner case like `{@summary {@return ...} ...}` which this patch and the complementary specification consider illegal anyway.
-------------
PR: https://git.openjdk.java.net/jdk/pull/1355
More information about the compiler-dev
mailing list