Please review the next round of update for definition lists in the
generated docs.
The primary focus of this round is to ensure that all <dl> elements have
the class attribute set.
In practice, there are only two kinds of definition lists:
* 1. the kind we now know as "notes", (where the <dt> elements are
bold and the <dd> elements not indented)
* 2. the entries in the index files.These previously did not have a
class attribute set, and so used the default style for definition
lists; these lists now have the class attribute set to "index",
although no specific style is defined for "index" at this point, and
so they continue to use the default style for definition lists.
By defining the class attribute on all definition lists, we set up being
able to simplify the stylesheet (in the next webrev) to remove
contentContainer nodes and friends.
The edits to the source files are generally simple, and mostly consist
of using new/improved factory methods for <dl> nodes that take a style
parameter. I have also done some local reordering of the code to setup
for another cleanup down the road. Previously, the code pattern was
* a. create the child <dt> node
* b. create the parent <dl> node containing the <dt> node
* c. create the child <dd> node and add it to the <dl> node
This was in response to a concern a long, long time ago about creating
and generating empty nodes: so the code style was to try and create
nodes with content, even though it led to the confusing sequence I just
described. The new sequence is:
* a. create the parent <dl> node
* b. create the child <dt> node and add it to the <dl> node
* c. create the child <dd> node and add it to the <dl> node
The reordering sets up the option to introduce and use chained method
calls in future, to simplify the code even more, but that was too much
of a change to add in this changeset.
There's a bunch of updates I could (and want to) make to the comments
throughout the HtmlTree class, but I think they should be done
separately so that the file has a consistent comment style.
One other item that became clear in this work is the use of "singleton
lists" in which there are a number of instances where the <dl> node is
always created with a single <dt>/<dd> pair. Moreover, a sequence of
these singleton lists may occur, depending on the characteristics of the
class being documented. This changeset does _not_ address that issue,
which should be handled separately. This is the definition-list
equivalent of the "sequence of singleton lists" that we fixed for <ul>
lists a while back!
The tests are generally just updated to expect the class attribute to be
set in <dl> elements.
-- Jon
JBS: https://bugs.openjdk.java.net/browse/JDK-8240136
Webrev: http://cr.openjdk.java.net/~jjg/8240136/webrev.00/index.html
