On Thu, 31 Aug 2023 22:53:49 GMT, Jonathan Gibbons <j...@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
