Hi Prasanta,
You mentioned the tool I was using to find the issues with headings...
It's a bit of a hack -- it's an annotation processor that can be run by
javac --
but while it is reasonably good at _detecting, it is not good at
checking that
you have fixed them _correctly_. This is because it is just checking
for some
simple heuristics in the sequence of headings, without any concept of the
semantic meaning of the headings.
As an example, if you had a class comment containing (just) two <h3>
headings, the tool will report that an <h2> is missing. If you fix the first
<h3>, so that the comment now has an <h2> and an <h3>, the tool
will not find any sequencing issues, but that second <h3> will now appear
semantically as a subheading of the <h2>, which was not the original
intent of the comment. (If we started using <section> as well as <hN>
we would be able to do better, but that's a different story.)
I don't have a good solution, except to say that if you update any heading
in any individual comment, you should (probably) update them all. One script
we could write as a verifier script would be to compare the number of
headings in a modified source file (using `grep -c`) with the number
of edits appearing in the output for `hg diff` for that file (again counted
with `grep -c`). That would at least make sure you haven't missed any
headings, but you'd still have to eyeball the edits to make sure they
have been modified correctly.
Finally, FWIW, I'm working on a fix for doclint, to improve its reporting
of these issues. The code is done, but I'm running tests, and will need
a review, so this will likely be early next week.
-- 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
