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