Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

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

Closed
wants to merge 5 commits into from

Conversation

pavelrappo
Copy link
Member

@pavelrappo pavelrappo commented Aug 30, 2023

This PR makes JavaDoc and DocLint produce more helpful diagnostic output when encounter an unknown tag.

Before:

MyClass.java:4: warning: no main description
 * @implSpite {@linkpain Object#hashCode}}
   ^
MyClass.java:4: error: unknown tag: implSpite
 * @implSpite {@linkpain Object#hashCode}}
   ^
MyClass.java:4: error: unknown tag: linkpain
 * @implSpite {@linkpain Object#hashCode}}
              ^
MyClass.java:5: error: unknown tag: danger
 * @danger
   ^

After:

 * @implSpite {@linkpain Object#hashCode}}
   ^
MyClass.java:4: error: unknown tag: implSpite; the most similar tags are: implSpec, implNote
 * @implSpite {@linkpain Object#hashCode}}
   ^
Note: An unknown tag has been reported. Mistyped? Forgot to add a custom tag or register a taglet?
MyClass.java:4: error: unknown tag: linkpain; the most similar tags are: linkplain
 * @implSpite {@linkpain Object#hashCode}}
              ^
MyClass.java:5: error: unknown tag: danger
 * @danger
   ^

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

  • Change must be properly reviewed (1 review required, with at least 1 Reviewer)
  • Change must not contain extraneous whitespace
  • Commit message must refer to an issue

Issue

  • JDK-8288660: JavaDoc should be more helpful if it doesn't recognize a tag (Bug - P4)

Reviewers

Reviewing

Using git

Checkout this PR locally:
$ git fetch https://git.openjdk.org/jdk.git pull/15494/head:pull/15494
$ git checkout pull/15494

Update a local copy of the PR:
$ git checkout pull/15494
$ git pull https://git.openjdk.org/jdk.git pull/15494/head

Using Skara CLI tools

Checkout this PR locally:
$ git pr checkout 15494

View PR using the GUI difftool:
$ git pr show -t 15494

Using diff file

Download this PR as a diff file:
https://git.openjdk.org/jdk/pull/15494.diff

Webrev

Link to Webrev Comment

@bridgekeeper
Copy link

bridgekeeper bot commented Aug 30, 2023

👋 Welcome back prappo! A progress list of the required criteria for merging this PR into master will be added to the body of your pull request. There are additional pull request commands available for use with this pull request.

@openjdk openjdk bot added the rfr Pull request is ready for review label Aug 30, 2023
@openjdk
Copy link

openjdk bot commented Aug 30, 2023

@pavelrappo The following labels will be automatically applied to this pull request:

  • compiler
  • javadoc

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 openjdk bot added javadoc javadoc-dev@openjdk.org compiler compiler-dev@openjdk.org labels Aug 30, 2023
@mlbridge
Copy link

mlbridge bot commented Aug 30, 2023

Webrevs

@hns
Copy link
Member

hns commented Aug 31, 2023

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, maybe this would also benefit from such handling?

@pavelrappo
Copy link
Member Author

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, 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".

Copy link
Contributor

@jonathan-gibbons jonathan-gibbons left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

@@ -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;
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Is there significance in 2.0 / 3 as compared to 0.667 etc

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

No. I can change it if you want me to.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

Comment on lines 88 to 90
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?
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Mild uugh at duplicate strings; maybe it's OK for now but is another reason to consolidate docent/javadoc behavior.

@pavelrappo
Copy link
Member Author

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.

testSimilarTags/src/x/MyClass.java:4: error: unknown tag. Mistyped @code or an unregistered custom tag?
 * {@cod}
   ^
testSimilarTags/src/x/MyClass.java:5: error: unknown tag. Unregistered custom tag?
 * {@codejdk.net.hosts.file}
   ^
testSimilarTags/src/x/MyClass.java:6: error: unknown tag. Mistyped @code or an unregistered custom tag?
 * {@coe}
   ^
testSimilarTags/src/x/MyClass.java:7: error: unknown tag. Mistyped @code or an unregistered custom tag?
 * {@cpde}
   ^
testSimilarTags/src/x/MyClass.java:8: error: unknown tag. Mistyped @code or an unregistered custom tag?
 * {@ocde}
   ^
testSimilarTags/src/x/MyClass.java:9: error: unknown tag. Mistyped @code or an unregistered custom tag?
 * {@ode}
   ^
testSimilarTags/src/x/MyClass.java:11: error: unknown tag. Mistyped @author or an unregistered custom tag?
 * @auther
   ^
testSimilarTags/src/x/MyClass.java:13: error: unknown tag. Mistyped @deprecated or an unregistered custom tag?
 * @Depricated
   ^
testSimilarTags/src/x/MyClass.java:14: error: unknown tag. Mistyped @deprecated or an unregistered custom tag?
 * @deprecation
   ^
testSimilarTags/src/x/MyClass.java:16: error: unknown tag. Mistyped @docRoot or an unregistered custom tag?
 * @DocRoot
   ^
testSimilarTags/src/x/MyClass.java:17: error: unknown tag. Mistyped @docRoot or an unregistered custom tag?
 * @dccRoot
   ^
testSimilarTags/src/x/MyClass.java:18: error: unknown tag. Mistyped @docRoot or an unregistered custom tag?
 * @docroot
   ^
testSimilarTags/src/x/MyClass.java:20: error: unknown tag. Mistyped @exception or an unregistered custom tag?
 * @ecception
   ^
testSimilarTags/src/x/MyClass.java:21: error: unknown tag. Mistyped @exception or an unregistered custom tag?
 * @excception
   ^
testSimilarTags/src/x/MyClass.java:22: error: unknown tag. Mistyped @exception or an unregistered custom tag?
 * @exceptbion
   ^
testSimilarTags/src/x/MyClass.java:23: error: unknown tag. Mistyped @exception or an unregistered custom tag?
 * @exceptino
   ^
testSimilarTags/src/x/MyClass.java:24: error: unknown tag. Mistyped @exception or an unregistered custom tag?
 * @exceptions
   ^
testSimilarTags/src/x/MyClass.java:25: error: unknown tag. Mistyped @exception or an unregistered custom tag?
 * @exceptoin
   ^
testSimilarTags/src/x/MyClass.java:26: error: unknown tag. Mistyped @exception or an unregistered custom tag?
 * @execption
   ^
testSimilarTags/src/x/MyClass.java:28: error: unknown tag. Mistyped @implNote or an unregistered custom tag?
 * @implnote
   ^
testSimilarTags/src/x/MyClass.java:30: error: unknown tag. Mistyped @inheritDoc or an unregistered custom tag?
 * @inheritdoc
   ^
testSimilarTags/src/x/MyClass.java:31: error: unknown tag. Mistyped @inheritDoc or an unregistered custom tag?
 * @inherotDoc
   ^
testSimilarTags/src/x/MyClass.java:32: error: unknown tag. Mistyped @inheritDoc or an unregistered custom tag?
 * @inheretdoc
   ^
testSimilarTags/src/x/MyClass.java:33: error: unknown tag. Mistyped @inheritDoc or an unregistered custom tag?
 * @inhertitDoc
   ^
testSimilarTags/src/x/MyClass.java:35: error: unknown tag. Mistyped @jvms or an unregistered custom tag?
 * @jvm
   ^
testSimilarTags/src/x/MyClass.java:36: error: unknown tag. Mistyped @jvms or an unregistered custom tag?
 * @jmvs
   ^
testSimilarTags/src/x/MyClass.java:38: error: unknown tag. Mistyped @link or an unregistered custom tag?
 * @Link
   ^
testSimilarTags/src/x/MyClass.java:39: error: unknown tag. Mistyped @link or an unregistered custom tag?
 * @linK
   ^
testSimilarTags/src/x/MyClass.java:40: error: unknown tag. Mistyped @link or an unregistered custom tag?
 * @linbk
   ^
testSimilarTags/src/x/MyClass.java:41: error: unknown tag. Mistyped @link or an unregistered custom tag?
 * @lini
   ^
testSimilarTags/src/x/MyClass.java:42: error: unknown tag. Mistyped @link or an unregistered custom tag?
 * @linke
   ^
testSimilarTags/src/x/MyClass.java:43: error: unknown tag. Mistyped @link or an unregistered custom tag?
 * @linked
   ^
testSimilarTags/src/x/MyClass.java:45: error: unknown tag. Mistyped @linkplain or an unregistered custom tag?
 * @linkplan
   ^
testSimilarTags/src/x/MyClass.java:47: error: unknown tag. Mistyped @param or an unregistered custom tag?
 * @params
   ^
testSimilarTags/src/x/MyClass.java:48: error: unknown tag. Mistyped @param or an unregistered custom tag?
 * @pararm
   ^
testSimilarTags/src/x/MyClass.java:49: error: unknown tag. Mistyped @param or an unregistered custom tag?
 * @parasm
   ^
testSimilarTags/src/x/MyClass.java:50: error: unknown tag. Mistyped @param or an unregistered custom tag?
 * @parem
   ^
testSimilarTags/src/x/MyClass.java:51: error: unknown tag. Mistyped @param or an unregistered custom tag?
 * @parm
   ^
testSimilarTags/src/x/MyClass.java:52: error: unknown tag. Mistyped @param or an unregistered custom tag?
 * @parma
   ^
testSimilarTags/src/x/MyClass.java:53: error: unknown tag. Mistyped @param or an unregistered custom tag?
 * @praam
   ^
testSimilarTags/src/x/MyClass.java:54: error: unknown tag. Unregistered custom tag?
 * @prarm
   ^
testSimilarTags/src/x/MyClass.java:56: error: unknown tag. Mistyped @return or an unregistered custom tag?
 * @Return
   ^
testSimilarTags/src/x/MyClass.java:57: error: unknown tag. Mistyped @return or an unregistered custom tag?
 * @eturn
   ^
testSimilarTags/src/x/MyClass.java:58: error: unknown tag. Unregistered custom tag?
 * @result
   ^
testSimilarTags/src/x/MyClass.java:59: error: unknown tag. Mistyped @return or an unregistered custom tag?
 * @retrun
   ^
testSimilarTags/src/x/MyClass.java:60: error: unknown tag. Mistyped @return or an unregistered custom tag?
 * @retuen
   ^
testSimilarTags/src/x/MyClass.java:61: error: unknown tag. Mistyped @return or an unregistered custom tag?
 * @retun
   ^
testSimilarTags/src/x/MyClass.java:62: error: unknown tag. Mistyped @return or an unregistered custom tag?
 * @retunr
   ^
testSimilarTags/src/x/MyClass.java:63: error: unknown tag. Mistyped @return or an unregistered custom tag?
 * @retur
   ^
testSimilarTags/src/x/MyClass.java:64: error: unknown tag. Mistyped @return or an unregistered custom tag?
 * @returns
   ^
testSimilarTags/src/x/MyClass.java:65: error: unknown tag. Mistyped @return or an unregistered custom tag?
 * @returnss
   ^
testSimilarTags/src/x/MyClass.java:66: error: unknown tag. Mistyped @return or an unregistered custom tag?
 * @retursn
   ^
testSimilarTags/src/x/MyClass.java:67: error: unknown tag. Mistyped @return or an unregistered custom tag?
 * @rturn
   ^
testSimilarTags/src/x/MyClass.java:69: error: unknown tag. Mistyped @see or an unregistered custom tag?
 * @See
   ^
testSimilarTags/src/x/MyClass.java:70: error: unknown tag. Mistyped @see or an unregistered custom tag?
 * @gsee
   ^
testSimilarTags/src/x/MyClass.java:72: error: unknown tag. Mistyped @serialData or an unregistered custom tag?
 * @serialdata
   ^
testSimilarTags/src/x/MyClass.java:74: error: unknown tag. Mistyped @since or an unregistered custom tag?
 * @sinc
   ^
testSimilarTags/src/x/MyClass.java:75: error: unknown tag. Mistyped @since or an unregistered custom tag?
 * @sine
   ^
testSimilarTags/src/x/MyClass.java:77: error: unknown tag. Mistyped @systemProperty or an unregistered custom tag?
 * @systemproperty
   ^
testSimilarTags/src/x/MyClass.java:79: error: unknown tag. Mistyped @throws or an unregistered custom tag?
 * @thows
   ^
testSimilarTags/src/x/MyClass.java:80: error: unknown tag. Mistyped @throws or an unregistered custom tag?
 * @thrown
   ^
testSimilarTags/src/x/MyClass.java:81: error: unknown tag. Mistyped @throws or an unregistered custom tag?
 * @throwss
   ^

@@ -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;
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

Comment on lines 87 to 88
dc.tag.unknown = unknown tag. Unregistered custom tag?
dc.tag.unknown.with.hint = unknown tag. Mistyped @{0} or an unregistered custom tag?
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

"one of these days", we will come up with a general style guide for diagnostic messages, and the (mixed) use of phrases and sentences!

@openjdk
Copy link

openjdk bot commented Sep 5, 2023

@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:

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

Reviewed-by: jjg

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 master branch:

  • aba89f2: 8312213: Remove unnecessary TEST instructions on x86 when flags reg will already be set
  • 1f4cdb3: 8315127: CDSMapTest fails with incorrect number of oop references
  • 939d7c5: 8161536: sun/security/pkcs11/sslecc/ClientJSSEServerJSSE.java fails with ProviderException
  • ebe3127: 8315717: ProblemList serviceability/sa/TestHeapDumpForInvokeDynamic.java with ZGC
  • 969fcdb: 8314191: C2 compilation fails with "bad AD file"
  • cef9fff: 8305507: Add support for grace period before AbortVMOnSafepointTimeout triggers
  • ed2b467: 8315499: build using devkit on Linux ppc64le RHEL puts path to devkit into libsplashscreen
  • 4b44575: 8305637: Remove Opaque1 nodes for Parse Predicates and clean up useless predicate elimination
  • 8647f00: 8293850: need a largest_committed metric for each category of NMT's output
  • 5a2e151: 8315548: G1: Document why VM_G1CollectForAllocation::doit() may allocate without completing a GC
  • ... and 3 more: https://git.openjdk.org/jdk/compare/fe4f90021ffd44cb0af34f39d4ca0a7e44605c92...master

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 master branch, type /integrate in a new comment.

@openjdk openjdk bot added the ready Pull request is ready to be integrated label Sep 5, 2023
 - Uses different (locale-specific) resources for HTML and JavaDoc tags
 - Updates hardcoded test strings
@pavelrappo
Copy link
Member Author

/integrate

@openjdk
Copy link

openjdk bot commented Sep 6, 2023

Going to push as commit a01b3fb.
Since your change was applied there have been 19 commits pushed to the master branch:

  • ba1a463: 8315377: C2: assert(u->find_out_with(Op_AddP) == nullptr) failed: more than 2 chained AddP nodes?
  • a258fc4: 8315648: Add test for JDK-8309979 changes
  • 5d3fdc1: 8315612: RISC-V: intrinsic for unsignedMultiplyHigh
  • 5cbff24: 8315406: [REDO] serviceability/jdwp/AllModulesCommandTest.java ignores VM flags
  • 7a08e6b: 8313575: Refactor PKCS11Test tests
  • d3ee704: 8315563: Remove references to JDK-8226420 from problem list
  • aba89f2: 8312213: Remove unnecessary TEST instructions on x86 when flags reg will already be set
  • 1f4cdb3: 8315127: CDSMapTest fails with incorrect number of oop references
  • 939d7c5: 8161536: sun/security/pkcs11/sslecc/ClientJSSEServerJSSE.java fails with ProviderException
  • ebe3127: 8315717: ProblemList serviceability/sa/TestHeapDumpForInvokeDynamic.java with ZGC
  • ... and 9 more: https://git.openjdk.org/jdk/compare/fe4f90021ffd44cb0af34f39d4ca0a7e44605c92...master

Your commit was automatically rebased without conflicts.

@openjdk openjdk bot added the integrated Pull request has been integrated label Sep 6, 2023
@openjdk openjdk bot closed this Sep 6, 2023
@openjdk openjdk bot removed ready Pull request is ready to be integrated rfr Pull request is ready for review labels Sep 6, 2023
@openjdk
Copy link

openjdk bot commented Sep 6, 2023

@pavelrappo Pushed as commit a01b3fb.

💡 You may see a message that your pull request was closed with unmerged commits. This can be safely ignored.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
compiler compiler-dev@openjdk.org integrated Pull request has been integrated javadoc javadoc-dev@openjdk.org
3 participants