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

[Alexey Ivanov]

Hi Prasanta,

Looks fine.

Regards,
Alexey

On 19/03/2019 10:41, Prasanta Sadhukhan wrote:
> Hi Alexey,
>
> Your points are valid so I modified those in this webrev, please have 
> a look
> http://cr.openjdk.java.net/~psadhukhan/8220250/webrev.3/
>
> Regards
> Prasanta
> On 15-Mar-19 10:28 PM, Alexey Ivanov wrote:
>> Hi Prasanta,
>>
>> On 15/03/2019 05:15, Prasanta Sadhukhan wrote:
>>>
>>> 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> - 
>>
>> Thank you for clarification. I've seen a few fixes in this area but I 
>> missed this discussion.
>>
>> So the main type heading will be <h1>, i.e. it will <h1>JTable</h1>. 
>> Therefore starting at <h2> in types makes sense.
>>
>>>> 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.
>>
>> According to the message you linked to, the documentation comments 
>> for methods should start at <h4>.
>>
>> Here's the relevant quote:
>> …Headings in documentation comments for modules, packages and types 
>> should start at <h2>;
>> Headings in documentation comments for members of a type (field, 
>> constructor, method, etc) should start at <h4>.
>>
>> (I've changed formatting to separate these two cases.)
>>
>>
>> Thus in *JTable.java* you should rather decrease heading level as the 
>> headings are used in /method/ as opposed to /type/ in the majority of 
>> other cases:
>> -3053      * <H3> Distributing the delta </H3>
>> +3053      * <H4> Distributing the delta </H4>
>>
>> -3055      * <H4> Overview </H4>
>> +3055      * <H5> Overview </H5>
>>
>> And the remaining <h4> become <h5>:
>> 3064      * <H4>Definition</H4>
>> 3096      * <H4>Details</H4>
>> 3107      * <H4>When the MAX and MIN bounds are hit</H4>
>>
>>
>> As for the rest of the review:
>>
>> *Font.java*
>>
>> You changed the first <h3> to <h2>:
>> -77  * <h3>Characters and Glyphs</h3>
>> +77  * <h2>Characters and Glyphs</h2>
>>
>> But why not other headings? All of the headings were at the same 
>> level, but they're not.
>>
>> These should also go up to <h2>:
>>  99  * <h3>Physical and Logical Fonts</h3>
>> 138  * <h3>Font Faces and Names</h3>
>> 172  * <h3>Font and TextAttribute</h3>
>>
>>
>> *javax/print/attribute/package-info.java*
>>
>> 204  * <h3>Attribute Class Design</h3>
>> 298  * <h3>Attribute Vendors</h3>
>> 324  * <h3>Using Attributes</h3>
>>
>> These should also go one level up to <h2> as other headings.
>> These used to be separate sections but now they're subsections of
>> 131  * <h2>Attribute Sets</h2>
>> which does not seem correct.
>>
>>
>> Regards,
>> Alexey
>>
>>>
>>> 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
>>>>>> <SNIP>
>>
>