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

[Prasanta Sadhukhan]

I have not changed any build files. I only modified CompileJavaModules 
to see if it builds fine as was asked for.

Regards
Prasanta
On 21-Mar-19 8:33 PM, Jonathan Gibbons wrote:
> Sounds good; note you should cc: build-dev at ojn for changes to build 
> files.
>
> -- Jon
>
> On 3/21/19 3:23 AM, Prasanta Sadhukhan wrote:
>> FYI...it does build fine with this build change.
>>
>> Regards
>> Prasanta
>> On 19-Mar-19 10:58 PM, Jonathan Gibbons wrote:
>>> Prasanta,
>>>
>>> Note that if you believe you have fixed all the heading issues in 
>>> the java.desktop module,
>>> you can re-enable the doclint checks for the module by removing 
>>> "-accessibility" from
>>> the java.desktop line in make/CompileJavaModules.gmk
>>>
>>> make/CompileJavaModules.gmk:java.desktop_ADD_JAVAC_FLAGS += 
>>> -Xdoclint:all/protected,-reference,-accessibility \
>>>
>>> If you do remove the option, make sure to run a build to verify that 
>>> doclint does not
>>> find any unfixed errors, which will prevent the build from 
>>> completing successfully.
>>>
>>> -- Jon
>>>
>>> On 3/19/19 3:41 AM, 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>
>>>>>
>>>>
>>