<Swing Dev> [13] RFR JDK-8220250: fix headings in java.desktop

[Jonathan Gibbons]

Hi Prasanta,

You mentioned the tool I was using to find the issues with headings...

It's a bit of a hack -- it's an annotation processor that can be run by 
javac --
but while it is reasonably good at _detecting, it is not good at 
checking that
you have fixed them _correctly_.  This is because it is just checking 
for some
simple heuristics in the sequence of headings, without any concept of the
semantic meaning of the headings.

As an example, if you had a class comment containing (just) two <h3>
headings, the tool will report that an <h2> is missing. If you fix the first
<h3>, so that the comment now has an <h2> and an <h3>, the tool
will not find any sequencing issues, but that second <h3> will now appear
semantically as a subheading of the <h2>, which was not the original
intent of the comment.  (If we started using <section> as well as <hN>
we would be able to do better, but that's a different story.)

I don't have a good solution, except to say that if you update any heading
in any individual comment, you should (probably) update them all. One script
we could write as a verifier script would be to compare the number of
headings in a modified source file (using `grep -c`) with the number
of edits appearing in the output for `hg diff` for that file (again counted
with `grep -c`).   That would at least make sure you haven't missed any
headings, but you'd still have to eyeball the edits to make sure they
have been modified correctly.

Finally, FWIW, I'm working on a fix for doclint, to improve its reporting
of these issues.  The code is done, but I'm running tests, and will need
a review, so this will likely be early next week.

-- Jon

On 3/8/19 7:09 AM, Prasanta Sadhukhan wrote:
> Hi Phil,
>
>
> On 08-Mar-19 9:17 AM, Philip Race wrote:
>> Apart from making sure all the files are fixed there are two things 
>> to look for :
>>
>> 1) If by moving a heading up from H3 to H2 you've now created a 
>> similar error
>> because there is now no H3 before an H4. To be sure of this I think 
>> you'd
>> need to run Jon's tool - how did you verify it ?
>>
> I missed one case in TextAttribute which I rectified
> http://cr.openjdk.java.net/~psadhukhan/8220250/webrev.1/
>  It will be good to have Jon's tool so cc-ed him...
>> 2) If in a case like UIManager where you've moved some subsequent 
>> headings
>> up from H3 to H2 to match the new size at the reported error site , 
>> would it
>> have been better visually to leave them as H3 ? ... probably not .. 
>> but if there
>> were generated doc for us to look at posted that would be easier to 
>> tell.
> I am using make docs to verify and the docs output can be found at
> http://cr.openjdk.java.net/~psadhukhan/8220250/docs/api/java.desktop/module-summary.html 
>
>
> Regards
> Prasanta
>>
>> -phil.
>>
>> On 3/8/19, 3:37 AM, Sergey Bylokhov wrote:
>>> Looks fine.
>>>
>>> On 07/03/2019 03:37, Prasanta Sadhukhan wrote:
>>>> Hi All,
>>>>
>>>> Bug: https://bugs.openjdk.java.net/browse/JDK-8220250
>>>> webrev: http://cr.openjdk.java.net/~psadhukhan/8220250/webrev.0/
>>>>
>>>> Please review a doc fix to fix heading style to improve the 
>>>> accessibility JDK API documentation of java.desktop module.
>>>>
>>>> Main approach taken for fixing heading style are:
>>>> - headings in documentation comments for modules, packages and 
>>>> types should start at <h2> - Headings should be hierarchical, and 
>>>> without ascending gaps, so <h1> should be followed by <h2>, <h2> 
>>>> should be followed by <h3> or another <h2> Regards Prasanta
>>>
>>>
>