RFR: 8288660: JavaDoc should be more helpful if it doesn't recognize a tag

[Pavel Rappo]

On Thu, 31 Aug 2023 22:53:49 GMT, Jonathan Gibbons <jjg at openjdk.org> wrote:

> This is a bit terse. I'd suggest to split it in two lines, the first containing a statement of fact. (`An unknown tag has been reported.`), and the second containing a more complete helpful sentence, such as "Did you mistype it, or forget to add a custom tag, or register a taglet?"

Maybe terse is okay? Also, while JavaDoc/DocLint messages are not very consistent stylistically, they don't normally use "you". The only exception is for the suggestion to file a bug against the javadoc.

Another aspect is roles. Do you remember javadoc roles: author, user, reader? The tool is run by the user. Just like it would be strange to ask the author "forget to add a custom tag, or register a taglet?", it would be strange to ask the user "Did you mistype it?", unless of course they are the same person.

> I know I suggested posting the message early, but if you post it at the end, it could be more of a summary, such as "5 different tags were reported 105 times; did you ..."

Okay, I'll revert the position.

-------------

PR Review Comment: https://git.openjdk.org/jdk/pull/15494#discussion_r1312792119