JDK-8253559: The INDEX page should link to Serialized Form and Constant Values pages #643
Conversation
|
👋 Welcome back jjg! A progress list of the required criteria for merging this PR into |
|
@jonathan-gibbons The following label 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 list. If you would like to change these labels, use the /label pull request command. |
Webrevs
|
(There is an equivalent field in `HtmlDocletWriter`)
There was a problem hiding this comment.
I'm surprised the mechanism to add links to the top of the index page can be generalized with so few changes.
I think this change needs to be checked and possibly tuned for the changes it causes to the search index contents. Basically we need to make sure these summary pages show up in the search results in the correct places (categories).
| @@ -2659,8 +2659,7 @@ public TreePath getTreePath(Element e) { | |||
| * A cache of doc comment info objects for elements. | |||
| * The entries may come from the AST and DocCommentParser, or may be autromatically | |||
| * generated comments for mandated elements and JavaFX properties. | |||
| * | |||
| * @see CommentUtils.dcInfoMap | |||
| ** @see CommentUtils#dcInfoMap | |||
There was a problem hiding this comment.
I think you unintentionally removed a line break while fixing the reference.
| if (item.isElementItem() || item.isTagItem()) { | ||
| // don't put summary-page items in the A-Z index: | ||
| // they are listed separately, at the top of the index page | ||
| itemsByFirstChar.computeIfAbsent(keyCharacter(item.getLabel()), |
There was a problem hiding this comment.
You're preventing these summary pages from showing up in the alphabetic index, but not from the by-category index below. This means they are added to the javadoc search contents, which by itself is a good thing. However, this means we also need to think about the category under which the item is listed. For example, you are using IndexItem.Category.MEMBER for the Deprecated API list, but deprecation applies to all element categories. I guess we should use the TAGS category for summary pages unless there is a clear element category they fit in?
There was a problem hiding this comment.
Initially, I put the summary pages in the alphabetic index as well, but it disrupted test files too much. It was sort-of silly to see All Classes and All Packages showing up under A in the alphabetic index when previously there was no A entry. Hence the change to the current behavior.
See next comment about which category to use.
| if (!deprapi.isEmpty() && configuration.mainIndex != null) { | ||
| configuration.mainIndex.add(IndexItem.of(IndexItem.Category.MEMBERS, | ||
| resources.getText("doclet.Deprecated_API"), path)); | ||
| } |
There was a problem hiding this comment.
IndexItem.Category.MEMBERS is probably not the correct category to use for the Deprecated API page, and we should choose a fitting category because these summary page items will end up in the search index (see my comment in IndexItem#add)
There was a problem hiding this comment.
Agreed. Now that you raise the issue, I realize that we should only use MODULE/PACKAGE/TYPES/MEMBERS for the appropriate kinds of elements, and should use TAGS for all "plain text" entries.
There was a problem hiding this comment.
Jon, I actually liked "All Classes" and "All Packages" being in the Types and Packages categories, respectively. I think it made sense to show them there and they were easier to find and use.
However, I understand it is conceptually cleaner this way and I don't want to start a bikeshedding session over it, so I give an approving review, but I would be interested in your thoughts about this.
|
@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: 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 53 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 |
|
Mailing list message from Jonathan Gibbons on javadoc-dev: On 10/16/20 4:16 AM, Hannes Walln?fer wrote:
Hi Hannes, Thanks for the feedback. I'll revert the changes related to "All However, as a follow-up, I think we should better document what kinds of -- Jon |
|
The only change in the latest commit is to back out the changes related to "All Classes" and "All Packages". Given that it builds and all tests still pass, I'll go with your earlier approval and integrate the change. |
|
/integrate |
openjdk
bot
added
integrated
|
@jonathan-gibbons Since your change was applied there have been 53 commits pushed to the
Your commit was automatically rebased without conflicts. Pushed as commit 83ea863. 💡 You may see a message that your pull request was closed with unmerged commits. This can be safely ignored. |
The mechanism to add links for summary pages in the main index is generalized, and now includes the Constant Values page, the Deprecated page and the Serialized Form page, provided these pages have non-empty content.
The only change to the generated output is very minor: the text of existing link to the "System Properties" page is changed to use a non-breaking space, in line with the links for "All Classes" and "All Packages".
Progress
Testing
Issue
Reviewers
Download
$ git fetch https://git.openjdk.java.net/jdk pull/643/head:pull/643$ git checkout pull/643