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

[Pavel Rappo]

On Thu, 31 Aug 2023 09:04:29 GMT, Hannes Wallnöfer <hannesw at openjdk.org> wrote:

> I really like this feature, but my immediate reaction is to also worry about decreased readability caused by increased verbosity. Some ideas:
> 
> * `the most similar tags are: ...` is quite long, and there are now 4 colon characters in that message line. Maybe the message could be something like `unknown tag implSpite, did you mean implSpec, implNote?`?
> * The `Note: An unknown tag has been reported...` message after the first unrecognized tag is a bit disruptive. I'm not sure it is needed, and if we want it maybe it should be at the end of the output? I have an open JBS issue to [generate a final message if any invalid input was encountered](https://bugs.openjdk.org/browse/JDK-8296175), maybe this would also benefit from such handling?

We can shorten both messages, but we have to make sure that the error reads clear on its own and both error and "Note" read well when combined. In particular, "Note" shouldn't provide information the error has already provided.

An orthogonal way to shorten the error would be to remove the tag name: we already have a caret (`^`) pointing to that tag in source. That said, it's not just these errors that duplicate information this way, it's many other errors in DocLint and to a lesser extent in JavaDoc.  

On ordering of "Note". When I showed this change to @jonathan-gibbons offline, before making it a PR, I had "Note" in the trailing position, much like the JBS proposal you linked to. To me it was natural: that's what I see first in my terminal. However, Jon noted that it might be better if "Note" followed the first relevant error, because that's how bugs from compiler and similar tools are generally fixed: you fix the first error, which might have caused all the following errors. So, I repositioned "Note".

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

PR Comment: https://git.openjdk.org/jdk/pull/15494#issuecomment-1700791590