RFR: JDK-8240138: Cleanup HtmlTree

[Pavel Rappo]

Hi Jon,

1. Some methods, constructors, enum constants, and unused imports have gone.

2. HtmlTree.HEADING(..., boolean printTitle, ...) has been split into 2 methods,
HtmlTree.HEADING and HtmlTree.HEADING_TITLE.

On a related note, it's satisfying to see that more and more calls to "new HtmlTree"
are being substituted with calls to convenience static factory methods.

3. The doc comments have been updated and cleaned up.

  ***

The bellow comments are for the preexisting issues in the code, incidentally
highlighted by this change.

1. We could switch from Collections.{emptyMap(), emptyList()} to {Map, List}.of()
in HtmlTree.

2. HtmlTree.EMPTY should probably be of FixedStringContent instead. Maybe it can
even be a specific final and immutable subtype of Content.

3. jdk.javadoc.internal.doclets.formats.html.markup.HtmlTree.add(java.lang.CharSequence)
The following part of the doc looks like an implementation detail, and maybe
should be an inline comment (or an @implNote) instead:

    * If the last content member that was added is a {@code StringContent},
    * append the string to that item; otherwise, create and use a new {@code StringContent}
    * for the new text content.

Also note, that the verbs are in imperative mood.

4. Should we just inline Content.nullCheck to Objects.requireNonNull across
the codebase at this stage?

5.  /**
     * Creates an HTML {@code SPAN} element with the given style and some content.
     *
     * @param body  the content
     * @return the element
     */
    public static HtmlTree SPAN(HtmlStyle styleClass, Content body) {}

"@param styleClass" is missing

Nits
====

Many of the below issues are also preexisting.

1. "Creates an {@code HTMLTree} object with a given kind of tag." should be {@code HtmlTree}

2. "Apply percent-encoding to a URL." should be in declarative mood, "Applies"

3. All the occurrences of "... and some content" read strangely to me
(as opposed to "given/specified/provided content" or similar)

4. Multiple occurrences of "* @param body  the content" (note an extra space)

5. "charSet" is cased strangely

6 "Adds additional content for the HTML element." smells like tautology

7. Do you think we should add a comment here?

    else if (content == HtmlTree.EMPTY || content.isValid()) {  /* implicit nullcheck for content */

8. Commas look strangely here:

    Creates an HTML {@code TH} element with the given scope, and some content.
    Creates an HTML {@code TH} element with the given style and scope, and some content.

9. The doc comment for HtmlTree.stripHtml is a bit messy.

10. Some conditional statements are missing curly braces.


Otherwise looks good to me. Thanks for doing this!

-Pavel

> On 10 Mar 2020, at 23:06, Jonathan Gibbons <jonathan.gibbons at oracle.com> wrote:
> 
> Please review another moderately simple cleanup, this time for the HtmlTree class.
> 
> The cleanup started as a general improvement to the null checking, but ended up including improvements to the documentation, and to the way that headings are created, the last of which involved corresponding changes at use sites.
> 
> Null-checking:
> 
> When generally building data structures that should not contain null, it is generally better to check for null when creating the data structure, to prevent NPEs much later on when the data is accessed.  But the HtmlTree class did excessive checking, which can be simplified to the points at which items are stored in the attributes or content of the tree nodes.
> 
> Cleaning up the null handling also involved cleaning up some overloaded methods in which null was being used to indicate an optional value, defeating the intent of the otherwise good null checking. This was most evident in the methods taking a 'style' parameter.
> 
> Documentation:
> 
> Previously, comments were added that used the word 'tag' as a way to avoid using the word 'element' to avoid confusion with the word 'element' as used to refer to an instance of javax.lang.model.element.Element. But that was an incorrect usage of 'tag'. The usage is corrected to used the term 'HTML element' instead. (The name of the HtmlTag class is also not ideal, but it is not proposed to change that at this time. If it were to be changed, it could be converted to HtmlTree.Kind)
> 
> Headings:
> 
> Some of the utility methods to create headings took a poorly named boolean parameter to indicate whether the title attribute should be set on the heading element. This lead to some clumsy implementation code. Instead, the overloads have been separated into two groups, with different names, ... those which do set the title attribute, and those which do not. This change affects use sites as well, which showed up other inconsistencies, such as not using the utility methods at all.
> 
> It is a separate question whether the title attribute should be set on any heading element: the answer is "probably not", but that issue is not addressed here, and is left for a separate followup. Changing this will probably affect tests and the goal of this changeset is to not affect any tests.
> 
> --------------
> 
> I suggest that the changes in HtmlTree are reviewed first. Once the changes to the utility methods to create headings are understood, the changes in the other files should be relatively simple to understand as well. There are a few additional cleanups, like minor reformatting changes and deleting unused declarations.
> 
> -- Jon
> 
> JBS: https://bugs.openjdk.java.net/browse/JDK-8240138
> Webrev: http://cr.openjdk.java.net/~jjg/8240138/webrev.00/index.html
>