8288660: JavaDoc should be more helpful if it doesn't recognize a tag #15494
Conversation
|
👋 Welcome back prappo! A progress list of the required criteria for merging this PR into |
|
@pavelrappo The following labels will be automatically applied to this pull request:
When this pull request is ready to be reviewed, an "RFR" email will be sent to the corresponding mailing lists. If you would like to change these labels, use the /label pull request command. |
openjdk
bot
added
javadoc
Webrevs
|
|
I really like this feature, but my immediate reaction is to also worry about decreased readability caused by increased verbosity. Some ideas:
|
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 ( 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". |
There was a problem hiding this comment.
I like the detection for misspellings.
I'm less convinced (at this time) by the helpful suggestion, but maybe it would eventually be OK when viewed in the context of a broader effort to give help hints, with some stylistic consistency as to their format.
I wonder if it would be interesting to treat helpful hints as a subcategory of notes so that all hints can be enabled or disabled with a single option. (i.e. we shouldn't change the distinction of error/warning/note but we might want to be able to identify "all hints", perhaps by a convention in the key name, etc.
src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/toolkit/resources/doclets.properties
Outdated
Show resolved
Hide resolved
| @@ -373,6 +376,29 @@ public void reportStats(PrintWriter out) { | |||
| Env env; | |||
| Checker checker; | |||
|
|
|||
| public static List<String> suggestSimilar(Collection<String> knownTags, String unknownTag) { | |||
| final double MIN_SIMILARITY = 2.0 / 3; | |||
There was a problem hiding this comment.
Is there significance in 2.0 / 3 as compared to 0.667 etc
There was a problem hiding this comment.
No. I can change it if you want me to.
There was a problem hiding this comment.
no biggie, except that the code makes you wonder at the implied specific precision here, as compared to a "simple" floating point number like 0.5 or even 0.75
| dc.tag.unknown.with.hint = unknown tag: {0}; the most similar tags are: {1} | ||
| dc.tag.unknown.help = An unknown tag has been reported. Mistyped? \ | ||
| Forgot to add a custom tag or register a taglet? |
There was a problem hiding this comment.
Mild uugh at duplicate strings; maybe it's OK for now but is another reason to consolidate docent/javadoc behavior.
|
Full disclosure. Below is the test output. Note that some tags are not recognized as similar enough, and that's fine. Catering for them would complicate the code. |
| @@ -373,6 +376,29 @@ public void reportStats(PrintWriter out) { | |||
| Env env; | |||
| Checker checker; | |||
|
|
|||
| public static List<String> suggestSimilar(Collection<String> knownTags, String unknownTag) { | |||
| final double MIN_SIMILARITY = 2.0 / 3; | |||
There was a problem hiding this comment.
no biggie, except that the code makes you wonder at the implied specific precision here, as compared to a "simple" floating point number like 0.5 or even 0.75
| dc.tag.unknown = unknown tag. Unregistered custom tag? | ||
| dc.tag.unknown.with.hint = unknown tag. Mistyped @{0} or an unregistered custom tag? |
There was a problem hiding this comment.
"one of these days", we will come up with a general style guide for diagnostic messages, and the (mixed) use of phrases and sentences!
|
@pavelrappo This change now passes all automated pre-integration checks. ℹ️ This project also has non-automated pre-integration requirements. Please see the file CONTRIBUTING.md for details. After integration, the commit message for the final commit will be: You can use pull request commands such as /summary, /contributor and /issue to adjust it as needed. At the time when this comment was updated there had been 13 new commits pushed to the
As there are no conflicts, your changes will automatically be rebased on top of these commits when integrating. If you prefer to avoid this automatic rebasing, please check the documentation for the /integrate command for further details. ➡️ To integrate this PR with the above commit message to the |
- Uses different (locale-specific) resources for HTML and JavaDoc tags - Updates hardcoded test strings
|
/integrate |
|
Going to push as commit a01b3fb.
Your commit was automatically rebased without conflicts. |
openjdk
bot
removed
ready
|
@pavelrappo Pushed as commit a01b3fb. 💡 You may see a message that your pull request was closed with unmerged commits. This can be safely ignored. |
This PR makes JavaDoc and DocLint produce more helpful diagnostic output when encounter an unknown tag.
Before:
After:
As you can see, the output has changed in two ways. Firstly, the tags that are similar to the unknown tag might be suggested. Secondly, an auxiliary note to help troubleshoot the unknown tag is provided. That note is provided once, close to the first reported unknown tag. This is done to not clutter the output in case multiple tags are reported.
For details, see the actual change.
Progress
Issue
Reviewers
Reviewing
Using
gitCheckout this PR locally:
$ git fetch https://git.openjdk.org/jdk.git pull/15494/head:pull/15494$ git checkout pull/15494Update a local copy of the PR:
$ git checkout pull/15494$ git pull https://git.openjdk.org/jdk.git pull/15494/headUsing Skara CLI tools
Checkout this PR locally:
$ git pr checkout 15494View PR using the GUI difftool:
$ git pr show -t 15494Using diff file
Download this PR as a diff file:
https://git.openjdk.org/jdk/pull/15494.diff
Webrev
Link to Webrev Comment