[jdk19] RFR: 6509045: {@inheritDoc} only copies one instance of the specified exception

[Jonathan Gibbons]

On Wed, 6 Jul 2022 17:05:19 GMT, Pavel Rappo <prappo at openjdk.org> wrote:

> This is the second of the two PRs that fix inheritance for multiple `@throws` tags for a particular exception.
> 
> The first PR (8067757, #95) fixed inheritance for multiple `@throws` tags for an exception referred to by a `throws` clause. This PR fixes inheritance for multiple `@throws` tags for an exception referred to by an `@throws` tag.
> 
> It is expected that if an overriding method has an `@throws` tag that has an `{@inheritDoc}` in its description, then the documentation will inherit all tags that describe that same exception in the overridden methods. For example, support the setup looks like this:
> 
> * Overrider
>    ```
>    @throws NullPointerException if this
>    @throws NullPointerException if that
>    ```
> 
> * Overridee
>    ```
>    @throws NullPointerException {@inheritDoc}
>    ```
> Then the overridee's documentation should look like this:
> 
> Throws:
> NullPointerException - if this
> NullPointerException - if that 
> 
> 
> While logical and expected, such behavior is different from other use cases of `{@inheritDoc}`. In other use cases `{@inheritDoc}` expands locally: it replaces itself with a list of tree nodes. Such a replacement doesn't affect any tree node other than its parent.
> 
> `{@inheritDoc}` expands locally everywhere, such as in the main description, `@param`, and `@return` tags, but it is not enough for `@throws`, which sometimes needs to amend the **grandparent** node to replace a `@throws` node with multiple `@throws` nodes. Amending this behavior globally just for `@throws` would be impractical.
> 
> For now, it seems reasonable to fix this by overriding the `{@inheritDoc}` processing just for `@throws`. This PR gives `ThrowsTaglet` an ability to peek at `@throws` description to see if there are any `{@inheritDoc}` there.
> 
> There's one limitation though. Suppose `@throws` documentation is both amended and inhertied from multiple `@throws` like this:
> 
> * Overridder
> 
> @throws NullPointerException if this
> @throws NullPointerException if that
> 
> 
> * Overridee
> 
> @throws NullPointerException "{@inheritDoc}"
> 
> 
> It's not clear what to do in such a case. If only one of either amendment (a `"` quote before and after) or multiple-inheritance is present, it's clear what to do. But not when both are present. For now, such a situation is detected and flagged as an error (a test is provided).

src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/toolkit/taglets/ThrowsTaglet.java line 204:

> 202:             return Map.of(tag, e);
> 203:         }
> 204:         // @throws is the only tag where it currently makes sense

I don't think it always makes sense, so I would weaken this to _where it may currently make sense_ or similar.

It can make sense if the entire description is `{@inheritDoc}`
I don't think it makes sense when `{@inheritDoc}` is part of a longer description, with additional text and tags alongside `{@inheritDoc}`. I would be inclined to specify that as a format restriction for the use of `{@inherotDoc}` in `@throws`.

src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/toolkit/taglets/ThrowsTaglet.java line 214:

> 212:         // 3. otherwise (tag does not add to it), add all tags
> 213:         var input = new DocFinder.Input(writer.configuration().utils, e, this, new DocFinder.DocTreeInfo(tag, e), false, true);
> 214:         var output = DocFinder.search(writer.configuration(), input);

Maybe use `var config = writer.configuration()` ?

src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/toolkit/taglets/ThrowsTaglet.java line 216:

> 214:         var output = DocFinder.search(configuration, input);
> 215:         if (output.tagList.size() <= 1) {
> 216:             // old code will doo just fine

peripatetic!

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

PR: https://git.openjdk.org/jdk19/pull/116