RFR: 8335122: Reorganize internal low-level support for HTML in jdk.javadoc [v7]

[Hannes Wallnöfer]

On Wed, 31 Jul 2024 18:00:11 GMT, Jonathan Gibbons <jjg at openjdk.org> wrote:

>> Please review a change to reorganize the internal low-level support for HTML in the jdk.javadoc module.
>> 
>> Hitherto, there are two separate sets of classes for low-level support for HTML in the `jdk.javadoc` module: one, in doclint, focused on reading and checking classes, the other, in the standard doclet, focused on generating HTML. This PR merges those two sets, into a new package `jdk.javadoc.internal.html` that is now used by both `doclint` and the standard doclet.
>> 
>> There was a naming "anti-clash" -- `HtmlTag` in `doclint` vs `TagName` in the standard doclet. The resolution is to use `HtmlTag`, since the merged class is more than just the tag name.
>> 
>> A few minor bugs were found and fixed.   Other minor cleanup was done, but otherwise, there should be no big surprises here. But, one small item of note: `enum HtmlStyle` was split into `interface HtmlStyle` and `enum HtmlStyles implements HtmlStyle` to avoid having a doclet-specific enum class in the new `internal.html` package.  The naming follows `HtmlId` and `HtmlIds`.
>> 
>> There is no attempt at this time to simplify `HtmlTag` and `HtmlAttr` to remove support for older versions of HTML.
>
> Jonathan Gibbons has updated the pull request with a new target base due to a merge or a rebase. The pull request now contains 12 commits:
> 
>  - Merge with upstream master;
>    add reference in HtmlTag to a related RFE
>  - Update/improve merge of HtmlTag and TagName
>  - Fix missing legal headers
>  - Cleanup use of HtmlStyle and HtmlStyles
>  - Fix merge issues
>  - Merge with upstream master
>  - fix whitespace
>  - reorder imports
>  - Cleanup pass
>  - Merge doclint into html: part 2: TagName/HtmlTag
>  - ... and 2 more: https://git.openjdk.org/jdk/compare/e4c7850c...2b6363ee

Looks good! It would be nice to have class-level doc comments in the new shared HTML classes.

src/jdk.javadoc/share/classes/jdk/javadoc/internal/html/HtmlAttr.java line 32:

> 30: import java.util.Locale;
> 31: 
> 32: public enum HtmlAttr {

Not essential, but it would be nice to have a simple class doc comment such as "Enum representing HTML tag attributes."

src/jdk.javadoc/share/classes/jdk/javadoc/internal/html/HtmlStyle.java line 28:

> 26: package jdk.javadoc.internal.html;
> 27: 
> 28: public interface HtmlStyle {

Again, a simple doc comment would be nice.

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

Marked as reviewed by hannesw (Reviewer).

PR Review: https://git.openjdk.org/jdk/pull/19916#pullrequestreview-2212514448
PR Review Comment: https://git.openjdk.org/jdk/pull/19916#discussion_r1700013819
PR Review Comment: https://git.openjdk.org/jdk/pull/19916#discussion_r1700014922