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

JDK-8253733: Cleanup internal taglet API #406

Closed

Conversation

@jonathan-gibbons
Copy link
Contributor

@jonathan-gibbons jonathan-gibbons commented Sep 29, 2020

This is a general cleanup of various classes related to the handling of tags and taglets in the standard doclet.

The initial motivation was to clean up static methods on TagletWriter that took a TagletWriter as a parameter. These methods are converted into instance methods, and the call sites simplified as well.

Another area of cleanup is to make clear which methods are used for inline tags and which are used for block tags.

Some dead code is removed, and the doc comments are generally cleaned up as well. More details are given in the JBS issue.


Progress

  • Change must not contain extraneous whitespace
  • Commit message must refer to an issue
  • Change must be properly reviewed

Issue

Reviewers

Download

$ git fetch https://git.openjdk.java.net/jdk pull/406/head:pull/406
$ git checkout pull/406

@bridgekeeper
Copy link

@bridgekeeper bridgekeeper bot commented Sep 29, 2020

👋 Welcome back jjg! 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.

Loading

@openjdk openjdk bot added the rfr label Sep 29, 2020
@openjdk
Copy link

@openjdk openjdk bot commented Sep 29, 2020

@jonathan-gibbons The following label will be automatically applied to this pull request:

  • javadoc

When this pull request is ready to be reviewed, an "RFR" email will be sent to the corresponding mailing list. If you would like to change these labels, use the /label pull request command.

Loading

@openjdk openjdk bot added the javadoc label Sep 29, 2020
@mlbridge
Copy link

@mlbridge mlbridge bot commented Sep 29, 2020

Webrevs

Loading

@jonathan-gibbons jonathan-gibbons changed the title 8253733: taglet api JDK-8253733: Cleanup internal taglet API Sep 30, 2020
Copy link
Member

@pavelrappo pavelrappo left a comment

These classes might need a copyright year update:

  1. jdk.javadoc.internal.doclets.toolkit.taglets.ValueTaglet
  2. jdk.javadoc.internal.doclets.toolkit.taglets.SystemPropertyTaglet
  3. jdk.javadoc.internal.doclets.toolkit.taglets.SummaryTaglet
  4. jdk.javadoc.internal.doclets.toolkit.taglets.SeeTaglet
  5. jdk.javadoc.internal.doclets.toolkit.taglets.ReturnTaglet
  6. jdk.javadoc.internal.doclets.toolkit.taglets.LiteralTaglet
  7. jdk.javadoc.internal.doclets.toolkit.taglets.IndexTaglet
  8. jdk.javadoc.internal.doclets.toolkit.taglets.DocRootTaglet
  9. jdk.javadoc.internal.doclets.toolkit.taglets.DeprecatedTaglet
  10. jdk.javadoc.internal.doclets.toolkit.taglets.CodeTaglet

It's easier to update copyright years unconditionally than to think whether or not a change amounts to a "substantial change".

Loading

*/
protected abstract Content getDocRootOutput();

/**
* Return the deprecated tag output.
* Returns the output for a {@code @deprecated ...} tag.
Copy link
Member

@pavelrappo pavelrappo Sep 30, 2020

Choose a reason for hiding this comment

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

In this file "ellipsis" is used for inline tags.

Loading

Copy link
Contributor Author

@jonathan-gibbons jonathan-gibbons Sep 30, 2020

Choose a reason for hiding this comment

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

OK.

Loading

*
* @param element the element to write deprecated documentation for.
* @return the output of the deprecated tag.
* @return the output
*/
protected abstract Content deprecatedTagOutput(Element element);

/**
* Return the output for a {@code {@literal ...}} tag.
Copy link
Member

@pavelrappo pavelrappo Sep 30, 2020

Choose a reason for hiding this comment

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

Add "s" to "Return" similarly to how you've done that for the rest of the methods.

Loading

Copy link
Contributor Author

@jonathan-gibbons jonathan-gibbons Sep 30, 2020

Choose a reason for hiding this comment

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

Good catch

Loading

output.add(currentOutput);
} catch (UnsupportedTagletOperationException e) {
// malformed taglet:
// claims to support block tags but does not provide the appropriate method.
Copy link
Member

@pavelrappo pavelrappo Sep 30, 2020

Choose a reason for hiding this comment

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

This deserves a more detailed explanation: what does this claim look like? (It's not obvious from reading this excerpt.)

Loading

Copy link
Contributor Author

@jonathan-gibbons jonathan-gibbons Sep 30, 2020

Choose a reason for hiding this comment

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

Fixed; for reference here, "claims to support" is a reference to Taglet.isBlockTag / Taglet.isInlineTag

Loading


/**
* @return an instance of the configuration used for this doclet.
* Returns an instance of the configuration used for this doclet.
Copy link
Member

@pavelrappo pavelrappo Sep 30, 2020

Choose a reason for hiding this comment

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

Remove extra whitespace in "Returns an".

Loading

Copy link
Contributor Author

@jonathan-gibbons jonathan-gibbons Sep 30, 2020

Choose a reason for hiding this comment

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

👍

Loading

public Content getTagletOutput(Element element, DocTree tag, TagletWriter writer) {
return header == null || tag == null ? null : writer.simpleTagOutput(element, tag, header);
public Content getInlineTagOutput(Element element, DocTree tag, TagletWriter writer) {
return null;
Copy link
Member

@pavelrappo pavelrappo Sep 30, 2020

Choose a reason for hiding this comment

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

I know that the corresponding simpleTagOutput method was deleted in this patch, but could you explain why this is a valid substitution?

Loading

Copy link
Contributor Author

@jonathan-gibbons jonathan-gibbons Sep 30, 2020

Choose a reason for hiding this comment

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

A better implementation would be remove this method, and rely on the underlying default impl to throw an exception; I'll change code to do that. The reason is that SimpleTag is only used for block tags, and this method is is (now) clearly for inline tags.

This sort of confusion in the original code was significant contributing factor in replacing the one name for two overloaded methods with two separate names for the different usages.

Loading

@jonathan-gibbons
Copy link
Contributor Author

@jonathan-gibbons jonathan-gibbons commented Sep 30, 2020

@pavelrappo , thanks for the list of files that need copyright updates; I've not yet figured out how to update the scripts that I used to use to update files, and I used to do it after review and before push, to minimize noise in the review. Old habits die hard.

Loading

@@ -279,7 +279,8 @@ public Content getBlockTagOutput(TagletManager tagletManager,
}
} catch (UnsupportedTagletOperationException e) {
// malformed taglet:
// claims to support block tags but does not provide the appropriate method.
// claims to support block tags (see Taglet.isBlockTag) but does not provide the
Copy link
Member

@pavelrappo pavelrappo Sep 30, 2020

Choose a reason for hiding this comment

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

This version does a better job of explaining your assumptions. Thanks.

(You don't need to address the below comment.)

I think this method could benefit from an assertion or an unconditional check that would guard against calling this method with a taglet list containing a non-block taglet. That is, a taglet t such that t.isBlockTag() == false.

This is a bit different from TagletWriter#getInlineTagOutput where the check is built into the method; TagletWriter#getBlockTagOutput relies on a caller to pass the correct list.

Loading

Copy link
Contributor Author

@jonathan-gibbons jonathan-gibbons Sep 30, 2020

Choose a reason for hiding this comment

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

Interesting question, worth considering ...

This is an internal API, so is only called from internal sites, with one of two lists supplied by the TagletManager: standard block tags, or serial form tags (the latter is why the list comes in as an argument and is not provided internally, as for inline tags.)

But given the list comes in as an argument, that suggests a reasonable update is to verify that all items in the argument list are block tags, and to throw ILA if any are not.

Loading

@openjdk
Copy link

@openjdk openjdk bot commented Sep 30, 2020

@jonathan-gibbons 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 more details.

After integration, the commit message for the final commit will be:

8253733: Cleanup internal taglet API

Reviewed-by: prappo

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 37 new commits pushed to the master branch:

  • e5ba020: 8253829: Wrong length compared in SSPI bridge
  • 9e453d9: 8239090: Improve CPU feature support in VM_Version
  • 8f7c9a7: 8252001: remove usage of PropertyResolvingWrapper in vmTestbase/nsk/jdi
  • 8cf8e46: 8253700: spurious "extends Throwable" at end of Optional.orElseThrow method declaration
  • 8b3d676: 8238737: remove DeoptimizeAllClassesRate from CTW library
  • 709cfe5: 8253815: Remove unused HeapRegionManager::_num_committed from SA
  • f80a606: 8253375: OSX build fails with Xcode 12.0 (12A7209)
  • 04775f1: 8253768: Deleting unused pipe_class definitions in adl-file (x86_64.ad).
  • dc3a0f5: 8253183: Fragile memory barrier selection for some weak memory model platforms
  • 8331e63: 8253778: ShenandoahSafepoint::is_at_shenandoah_safepoint should not access VMThread state from other threads
  • ... and 27 more: https://git.openjdk.java.net/jdk/compare/527b0e44eba9ec70cc2b3622a1d1e94b06b8017d...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.

Loading

@openjdk openjdk bot added the ready label Sep 30, 2020
Copy link
Member

@pavelrappo pavelrappo left a comment

Perfect, thanks!

Loading

@jonathan-gibbons
Copy link
Contributor Author

@jonathan-gibbons jonathan-gibbons commented Sep 30, 2020

/integrate

Loading

@openjdk openjdk bot closed this Sep 30, 2020
@openjdk openjdk bot added integrated and removed ready labels Sep 30, 2020
@openjdk
Copy link

@openjdk openjdk bot commented Sep 30, 2020

@jonathan-gibbons Since your change was applied there have been 37 commits pushed to the master branch:

  • e5ba020: 8253829: Wrong length compared in SSPI bridge
  • 9e453d9: 8239090: Improve CPU feature support in VM_Version
  • 8f7c9a7: 8252001: remove usage of PropertyResolvingWrapper in vmTestbase/nsk/jdi
  • 8cf8e46: 8253700: spurious "extends Throwable" at end of Optional.orElseThrow method declaration
  • 8b3d676: 8238737: remove DeoptimizeAllClassesRate from CTW library
  • 709cfe5: 8253815: Remove unused HeapRegionManager::_num_committed from SA
  • f80a606: 8253375: OSX build fails with Xcode 12.0 (12A7209)
  • 04775f1: 8253768: Deleting unused pipe_class definitions in adl-file (x86_64.ad).
  • dc3a0f5: 8253183: Fragile memory barrier selection for some weak memory model platforms
  • 8331e63: 8253778: ShenandoahSafepoint::is_at_shenandoah_safepoint should not access VMThread state from other threads
  • ... and 27 more: https://git.openjdk.java.net/jdk/compare/527b0e44eba9ec70cc2b3622a1d1e94b06b8017d...master

Your commit was automatically rebased without conflicts.

Pushed as commit 4fb8c77.

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

Loading

@openjdk openjdk bot removed the rfr label Sep 30, 2020
@jonathan-gibbons jonathan-gibbons deleted the 8253733-taglet-api branch Nov 4, 2020
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
2 participants