RFR: JDK-8075778: Add javadoc tag to avoid duplication of return information in simple situations. [v6]
Jonathan Gibbons
jjg at openjdk.java.net
Tue Dec 8 19:31:49 UTC 2020
On Tue, 8 Dec 2020 17:52:14 GMT, Pavel Rappo <prappo at openjdk.org> wrote:
>> Jonathan Gibbons has updated the pull request with a new target base due to a merge or a rebase. The incremental webrev excludes the unrelated changes brought in by the merge/rebase. The pull request contains 12 additional commits since the last revision:
>>
>> - Merge remote-tracking branch 'upstream/master' into new-return
>> - Update JShell to handle inline `{@return}`
>> - Merge remote-tracking branch 'upstream/master' into new-return
>> - fix test
>> - Update for new `@return` tag
>> - Merge remote-tracking branch 'upstream/master' into new-return
>> - Update DocCommentParser to permit nested inline tags in specified cases: @return
>> - Add default impl for new method
>> - Fix test failure
>> - Fix trailing whitespace in test
>> - ... and 2 more: https://git.openjdk.java.net/jdk/compare/695b9bdc...a25dadca
>
> 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!)
> src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclint/resources/doclint.properties line 60:
>
>> 58: dc.param.name.not.found = @param name not found
>> 59: dc.ref.not.found = reference not found
>> 60: dc.return.not.first = '{@return'} not at beginning of description
>
> I can see an inconsistency here. While the templates for `@return` and `@code` put an apostrophe immediately before the closing `}`, the template for `@value` (further below in this file) puts an apostrophe immediately after the closing `}`.
I'll investigate and follow up. It looks like general confusion whether to escape the curly braces, or to quote the enclosed text in the generated message.
-------------
PR: https://git.openjdk.java.net/jdk/pull/1355
More information about the compiler-dev
mailing list