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

[Pavel Rappo]

On Tue, 3 May 2022 19:30:01 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 with a new target base due to a merge or a rebase. The incremental webrev excludes the unrelated changes brought in by the merge/rebase. The pull request contains ten additional commits since the last revision:
> 
>  - Merge branch 'master' into 8285470
>  - (feedback) typography
>  - Update src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/toolkit/taglets/InheritDocTaglet.java
>    
>    Co-authored-by: ExE Boss <3889017+ExE-Boss at users.noreply.github.com>
>  - (fix) Fix a test failure
>    
>    Fixes a failure in jdk/javadoc/doclet/testInheritDocWithinInappropriateTag/TestInheritDocWithinInappropriateTag.java
>  - (cleanup) Simplify retrieveInheritedDocumentation
>  - (cleanup) Clarify retrieveInheritedDocumentation
>  - (cleanup) Unify specs of commentTagsToContent
>  - Stop passing "holderTag"
>  - (cleanup) Remove useless null check
>    
>    DocFinder.search cannot return null.

Thanks, Jon.

For the reader's convenience, let me link to that tree-search support improvement that you mentioned: JDK-8267690 (https://github.com/openjdk/jdk/pull/8369)

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

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