RFR: JDK-8287597: List all preview features on the javadoc PREVIEW page [v2]

[Hannes Wallnöfer]

On Thu, 22 Sep 2022 17:16:55 GMT, Hannes Wallnöfer <hannesw at openjdk.org> wrote:

>> Please review an enhancement to the preview page to add a list of preview features and allow users to explore the preview APIs by feature. 
>> 
>> While the changes for the enhancement itself are not overly complex, the work entailed a moderate cleanup of other summary API lists (Deprecated and New API pages) as well as a few unrelated summary pages that happened to share some of the CSS classes and HTML structure.
>> 
>> The change itself starts with a new internal `jdk.internal.javac.PreviewFeature.JEP` annotation interface to add JEP information to the nearby `jdk.internal.javac.PreviewFeature.Feature` enum. This JEP information is retrieved by new methods in the javadoc `Utils` class and then fetched by `PreviewAPIListBuilder` which passes it on to `PreviewListWriter`. 
>> 
>> The superclass of `PreviewListWriter` and other API summary writer classes, `SummaryListWriter`, gets a new `addContentSelectors(Content)` method to add the checkboxes to show/hide various parts of the page content. The class is also now abstract as this and other methods do not have useful implementations in the base class. 
>> 
>> Another change to `SummaryListWriter` is that `pageMode`, `description`, `headContent` and `titleKey` are no longer fields in the class but rather sent to the `generateSummaryListFile` method as parameters since they are mostly just used locally in that method. On the other hand, the associated Builder is used in many places and previously had to be retrieved from the configuration object or passed around as parameter, so that is now set as a final field in `SummaryListWriter`. 
>> 
>> Finally, a few words about changes in CSS and HTML: The "Contents" list containing various kinds of elements in the API list was previously contained in the `<div class="header">` element that also contains the page header, and the stylesheet used the `.header ul`  selector to style the list. Now that the checkboxes separate the page header from the contents list it felt wrong to put all this in the header div (most other pages only use the div for the header itself). I also didn't like the indirect CSS selector too much, `.header ul` is not very indicative of what it applies to.
>> 
>> I therefore decided to create a new dedicated CSS class for the contents list called `contents-list`, and move the `<ul>` element out of the header div. Apart from the summary API pages, this change also affects the "Constant Values"  page as well as the top and package level "Tree" (class hierarchy) pages. I made sure the contents list in these pages look the same as before.
>> 
>> The list items in the contents list now each have an `id` attribute to allow hiding the list item if no content for the element kind is currently selected/visible. The value of the `id` attribute uses the format `contents-<element-kind>`.
>> 
>> There is one additional CSS class called `preview-feature-list` used for the list of preview feature JEPs. 
>> 
>> Demo output for the new preview page as well as other pages is available here:
>> http://cr.openjdk.java.net/~hannesw/8287597/api.03/preview-list.html
>
> Hannes Wallnöfer has updated the pull request with a new target base due to a merge or a rebase. The pull request now contains two commits:
> 
>  - Merge branch 'master' into JDK-8287597
>  - JDK-8287597: List all preview features on the javadoc PREVIEW page

This pull request has been reopened, brought up to date with master and updated to address review feedback.

-------------

PR: https://git.openjdk.org/jdk/pull/9336