RFR: [S] 8211407: Bad links to non-existent entries on serialized-form page

[Jonathan Gibbons]

Please review a small fix, and medium test, that fixes hundreds(!) of broken
links in the JDK API documentation.

The broken links in question are generally all in the javax.swing.**
packages,
and are the "See Serialized Form" links in class documentation pages to the
serialized-form page. The package-info files for those directories are
not read
in a timely manner, meaning that the "@serial exclude" tag in those
directories is
effectively ignored at the time when links to the serialized form page
are being
generated. The package-info files are eventually lazily read, before
the serialized
form page is generated, and so the target of the (incorrect) link is
(correctly)
not generated, thus causing the broken link.

Although it's a javadoc problem and fix, the fix is way down in the javadoc
machinery that interacts with javac, in the JavadocEnter class. The fix
is to ensure that we call .complete() for the Symbol for the package-info
for any package for which we read a source file. Completing that symbol
is enough to ensure that the package-info.java file is read in a timely
manner.

A small combo test is written. The test is verified to fail without the fix
and to succeed with the fix. The regression is specific to the use of
packages in modules, containing `@serial exclude` although the test
covers additional test cases.

JBS: https://bugs.openjdk.java.net/browse/JDK-8211407
Webrev: http://cr.openjdk.java.net/~jjg/8211407/webrev.00/

-- Jon

[Jan Lahoda]

Looks good to me.

Jan

Post by Jonathan Gibbons
Please review a small fix, and medium test, that fixes hundreds(!) of broken
links in the JDK API documentation.
The broken links in question are generally all in the javax.swing.**
packages,
and are the "See Serialized Form" links in class documentation pages to the
serialized-form page. The package-info files for those directories are
not read
directories is
effectively ignored at the time when links to the serialized form page
are being
generated. The package-info files are eventually lazily read, before
the serialized
form page is generated, and so the target of the (incorrect) link is
(correctly)
not generated, thus causing the broken link.
Although it's a javadoc problem and fix, the fix is way down in the javadoc
machinery that interacts with javac, in the JavadocEnter class. The fix
is to ensure that we call .complete() for the Symbol for the package-info
for any package for which we read a source file. Completing that symbol
is enough to ensure that the package-info.java file is read in a timely
manner.
A small combo test is written. The test is verified to fail without the fix
and to succeed with the fix. The regression is specific to the use of
covers additional test cases.
JBS: https://bugs.openjdk.java.net/browse/JDK-8211407
Webrev: http://cr.openjdk.java.net/~jjg/8211407/webrev.00/
-- Jon

[Jonathan Gibbons]

Jan,

Thanks, but ... regrettably, the fix was a bit too clever and failed one
of the javadoc tests
that had annotations on a package declaration. It failed because javac
ended up trying
to add the annotations to the package twice, caused by calling
`.complete()` too soon.

So, this version is less aggressive, and just completes the package-info
symbols
on the included packages, after all other setup processing has been done.

This new test is unchanged, and this time all the javadoc tests pass.

-- Jon

Post by Jan Lahoda
Looks good to me.
Jan

Post by Jonathan Gibbons
Please review a small fix, and medium test, that fixes hundreds(!) of broken
links in the JDK API documentation.
The broken links in question are generally all in the javax.swing.**
packages,
and are the "See Serialized Form" links in class documentation pages to the
serialized-form page. The package-info files for those directories are
not read
directories is
effectively ignored at the time when links to the serialized form page
are being
generated. The package-info files are eventually lazily read, before
the serialized
form page is generated, and so the target of the (incorrect) link is
(correctly)
not generated, thus causing the broken link.
Although it's a javadoc problem and fix, the fix is way down in the javadoc
machinery that interacts with javac, in the JavadocEnter class. The fix
is to ensure that we call .complete() for the Symbol for the
package-info
for any package for which we read a source file. Completing that symbol
is enough to ensure that the package-info.java file is read in a timely
manner.
A small combo test is written. The test is verified to fail without the fix
and to succeed with the fix. The regression is specific to the use of
covers additional test cases.
JBS: https://bugs.openjdk.java.net/browse/JDK-8211407
Webrev: http://cr.openjdk.java.net/~jjg/8211407/webrev.00/
-- Jon

[Jonathan Gibbons]

Doh! I forgot to give a link to the updated webrev.

Updated webrev: http://cr.openjdk.java.net/~jjg/8211407/webrev.01/

-- Jon

Post by Jonathan Gibbons
Jan,
Thanks, but ... regrettably, the fix was a bit too clever and failed
one of the javadoc tests
that had annotations on a package declaration. It failed because javac
ended up trying
to add the annotations to the package twice, caused by calling
`.complete()` too soon.
So, this version is less aggressive, and just completes the
package-info symbols
on the included packages, after all other setup processing has been done.
This new test is unchanged, and this time all the javadoc tests pass.
-- Jon

Post by Jan Lahoda
Looks good to me.
Jan

Post by Jonathan Gibbons
Please review a small fix, and medium test, that fixes hundreds(!) of broken
links in the JDK API documentation.
The broken links in question are generally all in the javax.swing.**
packages,
and are the "See Serialized Form" links in class documentation pages to the
serialized-form page. The package-info files for those directories are
not read
directories is
effectively ignored at the time when links to the serialized form page
are being
generated. The package-info files are eventually lazily read, before
the serialized
form page is generated, and so the target of the (incorrect) link is
(correctly)
not generated, thus causing the broken link.
Although it's a javadoc problem and fix, the fix is way down in the javadoc
machinery that interacts with javac, in the JavadocEnter class. The fix
is to ensure that we call .complete() for the Symbol for the
package-info
for any package for which we read a source file. Completing that symbol
is enough to ensure that the package-info.java file is read in a timely
manner.
A small combo test is written. The test is verified to fail without the fix
and to succeed with the fix. The regression is specific to the use of
covers additional test cases.
JBS: https://bugs.openjdk.java.net/browse/JDK-8211407
Webrev: http://cr.openjdk.java.net/~jjg/8211407/webrev.00/
-- Jon

[Jan Lahoda]

Looks good to me.

Jan

Post by Jonathan Gibbons
Doh! I forgot to give a link to the updated webrev.
Updated webrev: http://cr.openjdk.java.net/~jjg/8211407/webrev.01/
-- Jon

Post by Jonathan Gibbons
Jan,
Thanks, but ... regrettably, the fix was a bit too clever and failed
one of the javadoc tests
that had annotations on a package declaration. It failed because javac
ended up trying
to add the annotations to the package twice, caused by calling
`.complete()` too soon.
So, this version is less aggressive, and just completes the
package-info symbols
on the included packages, after all other setup processing has been done.
This new test is unchanged, and this time all the javadoc tests pass.
-- Jon

Post by Jan Lahoda
Looks good to me.
Jan

Post by Jonathan Gibbons
Please review a small fix, and medium test, that fixes hundreds(!) of broken
links in the JDK API documentation.
The broken links in question are generally all in the javax.swing.**
packages,
and are the "See Serialized Form" links in class documentation pages to the
serialized-form page. The package-info files for those directories are
not read
directories is
effectively ignored at the time when links to the serialized form page
are being
generated. The package-info files are eventually lazily read, before
the serialized
form page is generated, and so the target of the (incorrect) link is
(correctly)
not generated, thus causing the broken link.
Although it's a javadoc problem and fix, the fix is way down in the javadoc
machinery that interacts with javac, in the JavadocEnter class. The fix
is to ensure that we call .complete() for the Symbol for the package-info
for any package for which we read a source file. Completing that symbol
is enough to ensure that the package-info.java file is read in a timely
manner.
A small combo test is written. The test is verified to fail without the fix
and to succeed with the fix. The regression is specific to the use of
covers additional test cases.
JBS: https://bugs.openjdk.java.net/browse/JDK-8211407
Webrev: http://cr.openjdk.java.net/~jjg/8211407/webrev.00/
-- Jon