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

Hannes Wallnöfer hannes.wallnoefer at oracle.com
Wed Jan 15 18:46:29 UTC 2020

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.


More information about the javadoc-dev mailing list