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>