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
