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
