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
