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

[Prasanta Sadhukhan]

Hi Alexey,


On 13-Mar-19 6:10 PM, Alexey Ivanov wrote:
> 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>.
As for this changeset, I am following the rules set in the 
https://mail.openjdk.java.net/pipermail/jdk-dev/2019-March/002671.html
- headings in documentation comments for modules, packages and types 
should start at <h2> -
>
> 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.
I have only changed to make sure there are no missing headings ie start 
with h2 (as stated above) and change previously used  h4 to h3(to make 
sure no missing heading), rest were as it was earlier.

Regards
Prasanta
>
> 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
>>>>>>>>>>>
>>>>>>>>>>>
>>>>>>>>>
>>>>>>>
>>>>>>
>>>>>>
>>>
>>
>

-------------- next part --------------
An HTML attachment was scrubbed...
URL: <https://mail.openjdk.java.net/pipermail/swing-dev/attachments/20190315/7de13f17/attachment.html>