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

[Alexey Ivanov]

Hi guys,

This is more of a general comment rather than targeted at this 
particular change. Sorry if I missed any previous discussion on that matter.

I think it's good to have consistent headings without skipping levels.

Yet <h2> in the Javadoc comments does not seem right. Let's take a look 
at JTable for example:
http://cr.openjdk.java.net/~psadhukhan/8220250/docs.webrev2/docs/api/java.desktop/javax/swing/JTable.html

The page starts with <h2>JTable</h2>. This is the highest heading level 
on the page, I haven't found any <h1>.

Later on, <h3>Method Detail</h3>. And a specific method: 
<h4>doLayout</h4>. Since the entire method description is under <h4> 
heading, it should not use any headings above <h4>. But now we have <h2> 
and <h3> which kind-of start new sections rather than being part of <h4> 
which describes the method.

Is such heading sequence intended?

Regards,
Alexey

On 13/03/2019 06:10, Prasanta Sadhukhan wrote:
> Any more comments on this 
> http://cr.openjdk.java.net/~psadhukhan/8220250/webrev.2/
>
> Regards
> Prasanta
> On 11-Mar-19 2:16 PM, Prasanta Sadhukhan wrote:
>> The 2nd URL is based on webrev.1. I have placed new docs for webrev.2 
>> here 
>> http://cr.openjdk.java.net/~psadhukhan/8220250/docs.webrev2/docs/api/java.desktop/module-summary.html 
>>
>>
>> Regards
>> Prasanta
>> On 10-Mar-19 9:17 PM, Jonathan Gibbons wrote:
>>> If it helps, I have a utility to extract headers from an API bundle, 
>>> that can generate a new bundle showing just the headers for each 
>>> page, and their metadata. I'll run that on the two bundles you list 
>>> below, and post the new URLs here.
>>>
>>> -- Jon
>>>
>>> On 3/9/19 10:59 PM, Philip Race wrote:
>>>> It might have been intentional but I think it is wrong.
>>>>
>>>> It is useful to look at the old :
>>>> https://docs.oracle.com/en/java/javase/11/docs/api/java.desktop/module-summary.html 
>>>>
>>>> and the new :
>>>> http://cr.openjdk.java.net/~psadhukhan/8220250/docs/api/java.desktop/module-summary.html 
>>>>
>>>>
>>>> to compare.
>>>>
>>>>
>>>> What was H3 is in italics and what follows in regular style is 
>>>> intended
>>>> to be a sub-section.
>>>>
>>>> -phil.
>>>>
>>>> On 3/10/19, 9:30 AM, Sergey Bylokhov wrote:
>>>>> When I check the first version, I thought it was intentional change.
>>>>>
>>>>> https://docs.oracle.com/en/java/javase/11/docs/api/java.desktop/javax/print/attribute/package-summary.html 
>>>>>
>>>>>
>>>>> All of them looks similar headers described something about 
>>>>> attributes:
>>>>>   1. <h4><a id="role"></a>Attribute Roles</h4>
>>>>>   2. <h3>Attribute Sets</h3>
>>>>>
>>>>> Why the first uses <h4> and the second uses <h3>?
>>>>>
>>>>> On 09/03/2019 01:54, Prasanta Sadhukhan wrote:
>>>>>> Thanks Jon for the pointer. I have modified that file
>>>>>>
>>>>>> http://cr.openjdk.java.net/~psadhukhan/8220250/webrev.2/
>>>>>>
>>>>>> Any more comments?
>>>>>>
>>>>>> Regards
>>>>>> Prasanta
>>>>>> On 09-Mar-19 2:24 AM, Jonathan Gibbons wrote:
>>>>>>> Prasanta,
>>>>>>>
>>>>>>> You should double check this file:
>>>>>>>
>>>>>>> http://cr.openjdk.java.net/~psadhukhan/8220250/webrev.1/src/java.desktop/share/classes/javax/print/attribute/package-info.java.udiff.html 
>>>>>>>
>>>>>>>
>>>>>>> Previously, it was a mixture of <h3> and <h4>, suggesting that 
>>>>>>> the <h4> were subheadings of the enclosing logical <h3> 
>>>>>>> section.  Now, you have changed them all to <h2>, meaning that 
>>>>>>> now they are all equivalent headings.
>>>>>>>
>>>>>>> -- 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
>>>>>>>>>>
>>>>>>>>>>
>>>>>>>>
>>>>>>
>>>>>
>>>>>
>>
>