RFR: JDK-8240916 Convert to using hyphenated naming for CSS classes
Jonathan Gibbons
jonathan.gibbons at oracle.com
Thu Mar 12 02:12:02 UTC 2020
Please review a mostly-simple change to convert javadoc to using
hyphenated-naming instead of camelCase naming for CSS class names in the
stylesheet. This is a big step towards using modern naming conventions.
The change starts off in HtmlStyle.java, where the hyphenated names are
generated automatically, but with the possibility of specifying them
explicitly.
There is (obviously) a corresponding change in the stylesheet, and
downstream there are changes in lots of tests. These changes were
"mostly automated" by creating a sed script to convert old-style names
to new-style names. The sed script got maybe 95% of the way there, but
some manual fixup was necessary: for example, for false positive matches.
In the source code, it was necessary to ensure that the correct form of
the name was used in the HtmlTree, and in one case, the natural (Java)
name is used explicitly to generate a JavaScript name. (Previously, all
cases just used .toString()). And, as has often recently been the case,
some outlier uses of direct construction of HtmlTree nodes is replaced
by the appropriate typesafe factory method.
Note: the end goal is to move towards more structured naming, perhaps
based on the BEM naming conventions. This change is not that, although
it is a big and necessary step in that direction. The existing naming is
too irregular to attempt to convert everything to BEM naming at this
time; instead, going forward, we can identify blocks and the
corresponding groups of names and convert them in stages, such as for
summary blocks, details blocks, and individual detail blocks. That will
also be a good time to document the names being used.
Because this potentially impacts the visual presentation, I've included
a copy of the generated JDK API docs using the new naming. The intent is
that the change should not affect the pixels on the screen, and
everything should look and work exactly as before.
-- Jon
JBS: https://bugs.openjdk.java.net/browse/JDK-8240916
Webrev: http://cr.openjdk.java.net/~jjg/8240916/webrev.00/index.html
API: http://cr.openjdk.java.net/~jjg/8240916/api.00/index.html
More information about the javadoc-dev
mailing list