RFR: JDK-8075778: Add javadoc tag to avoid duplication of return information in simple situations. [v6]

[Jonathan Gibbons]

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