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-8259283: use new HtmlId and HtmlIds classes #1951

Closed
wants to merge 6 commits into from

Conversation

jonathan-gibbons
Copy link
Contributor

@jonathan-gibbons jonathan-gibbons commented Jan 6, 2021

Please review this change to centralize the management of HTML ids used by the standard doclet in a single new factory class, HtmlIds, which utilizes a new type-safe wrapper class around String called HtmlId.

The new classes are used both when declaring ids (e.g. HtmlTree.setId) and when referencing them (e.g. Links.createLink). The enum SectionName, which declared a set of standard ids, goes away, as do methods in Links and other places to create "anchors".

This is a simple refactoring: there is no intentional change of functionality, and no tests are affected or need to be updated. However, the changes do highlight the inconsistency of the use of ids: it would be good to rationalize these in separate, targeted follow-up work.


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/1951/head:pull/1951
$ git checkout pull/1951

@bridgekeeper
Copy link

@bridgekeeper bridgekeeper bot commented Jan 6, 2021

👋 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.

@openjdk
Copy link

@openjdk openjdk bot commented Jan 6, 2021

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

@openjdk openjdk bot added the javadoc label Jan 6, 2021
@openjdk openjdk bot added the rfr label Jan 6, 2021
@mlbridge
Copy link

@mlbridge mlbridge bot commented Jan 6, 2021

Webrevs

…lve conflicts

# Conflicts:
#	src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/DeprecatedListWriter.java
#	src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/HtmlDocletWriter.java
#	src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/Navigation.java
hns
hns approved these changes Jan 13, 2021
Copy link
Member

@hns hns left a comment

Very nice work, Jon! +1

A few inline comments for an unused field and method and a couple of questions.

*/
public String getName(String name) {
return name.replaceAll("\\s+", "");
public Content createExternalLink(DocLink link, Content label) {
Copy link
Member

@hns hns Jan 13, 2021

Choose a reason for hiding this comment

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

The createLink(DocLink, Content, boolan) method above (line #221) that is replaced by this new method is not used anymore (and within it, the boolean parameter is not used).

Copy link
Contributor Author

@jonathan-gibbons jonathan-gibbons Jan 13, 2021

Choose a reason for hiding this comment

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

Ah, good catch! Will fix.

@@ -299,16 +298,21 @@ public void addRow(Element element, List<Content> contents) {
int rowIndex = bodyRows.size();
rowStyle = stripedStyles.get(rowIndex % 2);
}
Set<String> tabClasses = new HashSet<>();
Set<String> tabClasses = new HashSet<>(); // !! would be better as a List
Copy link
Member

@hns hns Jan 13, 2021

Choose a reason for hiding this comment

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

I assume no bug has been filed for this?

Copy link
Contributor Author

@jonathan-gibbons jonathan-gibbons Jan 13, 2021

Choose a reason for hiding this comment

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

Not yet. I have a list of a number of minor cleanups to do.

@@ -71,9 +72,10 @@
HtmlIndexBuilder(HtmlConfiguration configuration) {
super(configuration, configuration.getOptions().noDeprecated());
this.configuration = configuration;
links = new Links(DocPath.empty, configuration.utils);
links = new Links(DocPath.empty);
Copy link
Member

@hns hns Jan 13, 2021

Choose a reason for hiding this comment

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

It looks like links isn't used anywhere else in HtmlIndexBuilder and can be removed.

Copy link
Contributor Author

@jonathan-gibbons jonathan-gibbons Jan 13, 2021

Choose a reason for hiding this comment

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

OK, will check.

*
* @see HtmlTree#setId(HtmlId)
*/
public interface HtmlId {
Copy link
Member

@hns hns Jan 13, 2021

Choose a reason for hiding this comment

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

Is there a reason for making this an interface instead of a plain class?

Copy link
Contributor Author

@jonathan-gibbons jonathan-gibbons Jan 13, 2021

Choose a reason for hiding this comment

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

At one point, I had in mind using an enum class for the set of fixed ids, and so wanted an interface that I could mix in to the declaration of that class.

Eventually, when we have value types, HtmlId could be a good candidate for that feature.

@openjdk
Copy link

@openjdk openjdk bot commented Jan 13, 2021

@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 details.

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

8259283: use new HtmlId and HtmlIds classes

Reviewed-by: hannesw

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 no new commits pushed to the master branch. If another commit should be pushed before you perform the /integrate command, your PR will be automatically rebased. If you prefer to avoid any potential 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 label Jan 13, 2021
@jonathan-gibbons
Copy link
Contributor Author

@jonathan-gibbons jonathan-gibbons commented Jan 13, 2021

/integrate

@openjdk openjdk bot closed this Jan 13, 2021
@openjdk openjdk bot added integrated and removed ready rfr labels Jan 13, 2021
@jonathan-gibbons jonathan-gibbons deleted the htmlids branch Jan 13, 2021
@openjdk
Copy link

@openjdk openjdk bot commented Jan 13, 2021

@jonathan-gibbons Pushed as commit 916ab4e.

💡 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
integrated javadoc
2 participants