RFR: 8285470: Improve handling of @inheritDoc [v2]

[ExE Boss]

On Fri, 22 Apr 2022 15:50:28 GMT, Pavel Rappo <prappo at openjdk.org> wrote:

>> The only taglet that along with its own tag needs to know the immediately enclosing tag is `InheritDocTaglet`:
>> 
>>     @return {@inheritDoc}
>>     @throws NullPointerException {@inheritDoc}
>>     @param p {@inheritDoc}
>> 
>> However, the immediately enclosing tag is unconditionally passed to all taglets. If we stop passing it and make `InheritDocTaglet` compute it instead, the code becomes cleaner.
>> 
>> While reviewing, particularly note these benefits of the proposed change:
>> 
>>  * taglet-handling code knows less about `@inheritDoc`, and
>>  * `InheritDocTaglet` receives its own tag, not the tag that encloses it
>
> Pavel Rappo has updated the pull request incrementally with one additional commit since the last revision:
> 
>   (fix) Fix a test failure
>   
>   Fixes a failure in jdk/javadoc/doclet/testInheritDocWithinInappropriateTag/TestInheritDocWithinInappropriateTag.java

src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/toolkit/taglets/InheritDocTaglet.java line 64:

> 62:      * This method does not expand all {@code {@inheritDoc}} tags in the given
> 63:      * element's doc comment. To do this, the method must be called for every
> 64:      * such tag.

This should probably be wrapped in a `<p>` tag:
Suggestion:

     * <p>This method does not expand all {@code {@inheritDoc}} tags in the given
     * element's doc comment. To do this, the method must be called for every
     * such tag.</p>

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

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