Please review a change to cleanup/simplify the HTML and CSS used to
present block tags, like @see, @since, etc.
Currently, the information from these tags is presented in a definition
list (<dl>). The labels, in the <dt> nodes, are wrapped in <span> using
an inconsistent set of CSS class names. Sometimes the names are shared,
sometimes they are unique.
With this change, a new CSS class "blockTags" is put on the enclosing
<dl> node, and the <span> nodes wrapping the individual labels removed.
This does mean that it is no longer possible to style some of the labels
individually, but the use of CSS class names that were sometimes shared,
sometime unique, makes it unlikely that anyone tried to do this. If (and
only if) there is a demand to style tags individually, that should be
handled as a new Enhancement request, that might involve putting
tag-specific CSS class names on the <dt> and <dd> nodes for each tag
(i.e. without an additional <span>).
There is one anomaly. The definition list for the block tags for a
method is also used to present information when the method overrides or
implements a method from a supertype. That makes the new CSS class name
of "blockTags" slightly less than ideal. Suggestions for a better name
are welcome.
The code to generate the overall list of tags for any element is not as
centralized as might be desired. This changeset does not attempt to fix
that.
There should be no visible change to docs generated using the default
stylesheet when the docs are viewed in a browser.
The src/ code changes are relatively simple, and just consist of
adjusting the HTML and CSS that is generated. In some cases, there is
some additional code cleanup. About 30 tests are affected, although the
changes are generally simple and localized. The bug number has been
added to the @bug list for a subset of the tests; there are no new
additional tests.
---
A separate exercise would be to identify other <dl> nodes generated by
the doclet, and to add a CSS class to those nodes to identify the kind
of list.
-- Jon
JBS: https://bugs.openjdk.java.net/browse/JDK-8239804
Webrev: http://cr.openjdk.java.net/~jjg/8239804/webrev.00/
