RFR: 8224052: Javadoc doesn't handle non-public intermediate types well

[Jonathan Gibbons]

Approved.

For subsequent followup, the following is a pre-existing condition and 
not new to your patch ....
I wonder why alreadyDocumented is a Set<String> ... would it not be 
better as a Set<TypeElement>?
I see it was declared as Set<String> back in JDK 8 javadoc, so it may be 
that this is just "old code" that did not get properly modernized in the 
conversion to the new doclet.

As regards package-private and private intermediate supertypes, in the 
absence of any pre-existing comment to the contrary, your inclusion of 
isPrivate in isUndocumentedEnclosure is morally justifiable, even if it 
is a change in behavior in an absurdly weird corner case that (to the 
best of my knowledge) is undocumented.

-- Jon


On 01/15/2020 10:46 AM, Hannes Wallnöfer wrote:
> Please review:
>
> JBS: https://bugs.openjdk.java.net/browse/JDK-8224052
> Webrev: http://cr.openjdk.java.net/~hannesw/8224052/webrev.00/
>
> This is based on Maurizio’s patch, which fixes signatures of instantiated generic methods in javadoc pages.
>
> What was missing was support for the @throws taglet, which happens to be the only javadoc taglet that actually displays type names. Unfortunately fixing @throws was rather involved. I first had to add getCurrentPageElement() methods in TagletWriter and HtmlDocletWriter to let taglets retrieve the current type element as suggested by Jon on the JBS issue. We then set up a map of type variables to their type substitutes. This seemed like the simplest way to go since there is no fixed correlation between the list of thrown types and @throws tags; tags may be missing, in no particular order etc.
>
> There was another problem in ThrowsTaglet where Utils.getFullyQualifiedName(Element) was used to keep track of already documented thrown types in ThrowsTaglet. However, this replaces type-variables with the name of the enclosing type, so thrown type vars were not tracked correctly and could be documented multiple times. This is fixed by using Utils.getFullyQualifiedName(Element, boolean) instead and passing false as second argument.
>
> Finally, as hinted by Jon on JBS, there was a bug where methods inherited from private intermediate classes where not documented. This is also fixed by accepting private types in Utils.isUndocumentedEnclosure(TypeElement).
>
> Another problem I found with methods inherited this way is that they are not included in the search index. I’ll file a new JBS issue for this.
>
> Hannes