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

[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


On 10/03/2018 12:07 PM, Jan Lahoda wrote:
> Looks good to me.
>
> Jan
>
> On 3.10.2018 02:24, Jonathan Gibbons wrote:
>> 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
>>
>>
>>
>>