RFR: JDK-8157682: @inheritDoc doesn't work with @exception

[Pavel Rappo]

On Wed, 3 Mar 2021 22:22:29 GMT, Jonathan Gibbons <jjg at openjdk.org> wrote:

> Please review a fix to improve the handling of the legacy `@exception` tag.
> 
> A patch for this was [previously submitted](https://mail.openjdk.java.net/pipermail/javadoc-dev/2019-September/001139.html). However, that patch introduced an explicit new `ExceptionTaglet` class, whereas the fix here just reuses the existing `ThrowsTaglet`, registering it under an additional name.
> 
> The test in the original patch is enhanced to check all 4 combinations of (throws, exception) in the base class and (throws, exception) in the subclass.

This commit changes the order of block tags in the output. The fact that no tests failed when I ran them surprised me. I think we should both fix that order and introduce a test for it.

src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/toolkit/taglets/TagletManager.java line 741:

> 739:     private void showTaglets(PrintStream out) {
> 740:         Map<String, Taglet> taglets = new TreeMap<String, Taglet>();
> 741:         taglets.putAll(allTaglets);

Consider squashing these two lines into one:
Map<String, Taglet> taglets = new TreeMap<>(allTaglets);
and deleting this now unused import:
import java.util.Comparator;

src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/toolkit/taglets/TagletManager.java line 590:

> 588:                     if (!list.contains(t)) {
> 589:                         list.add(t);
> 590:                     }

I suppose the purpose of that is to filter out a now duplicated `ThrowsTaglet`. We should separately consider using a more appropriate data structure there.

-------------

Changes requested by prappo (Reviewer).

PR: https://git.openjdk.java.net/jdk/pull/2818