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>
