RFR: JDK-8240138: Cleanup HtmlTree

[Jonathan Gibbons]

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