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:39:34 UTC 2020
On Tue, 8 Dec 2020 19:29:15 GMT, Jonathan Gibbons <jjg at openjdk.org> wrote:
>> 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.
It looks like the quotes are never needed. I'll remove all of them.
`
/**
* This is a comment.
* This is a bad {@return fred}
* This is a bad {@value}
* This is a bad <code>{@code code}</code>.
*/
public class C { }
`
`
play/doclint-msgs/src/C.java:3: warning: {@return} not at beginning of description
* This is a bad {@return fred}
^
play/doclint-msgs/src/C.java:3: error: invalid use of @return
* This is a bad {@return fred}
^
play/doclint-msgs/src/C.java:4: error: {@value} not allowed here
* This is a bad {@value}
^
play/doclint-msgs/src/C.java:5: warning: {@code} within <code>
* This is a bad <code>{@code code}</code>.
^
2 errors
2 warnings
`
-------------
PR: https://git.openjdk.java.net/jdk/pull/1355
More information about the compiler-dev
mailing list