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

[Pavel Rappo]

On Mon, 25 Apr 2022 23:12:43 GMT, Jonathan Gibbons <jjg at openjdk.org> wrote:

> This one is somewhat questionable.
> 
> Generally, the trees in `javac` and `javadoc` do not store parent pointers (to save space), leading to a general coding philosophy of "collect any necessary information as you walk down the tree". I understand why you want to get rid of the extra parameters, but it is disappointing to see the code use a tree-walk (even if we have recently improved it) to re-acquire info that was already available a few stack-frames up.
> 
> Since the magic/use is primarily in `TagletWriter/Impl` with most other edits being to propagate the info, is there any better way to make the `holder` available, without having to call `getDocTreePath`? For example, `HtmlDocWriter` creates a `TagletWriter round about line 381: is there a way we could stash the holder in that object for later retrieval by the `InheritDocTaglet`.
> 
> I would hate for this PR to be seen as a precedent for more widespread use of `get[Doc]TreePath`.

I think that this improvement in readability wins over the miniscule performance hit it brings. Currently, walking down the stack feels like telling a story with too many details too soon.

Speaking of irrelevant details. The related `DocFinder` subsystem is even worse. Its `Input` and `Output` classes are full of fields used by specific taglets. I'm not a fan of this "a bag of everything" pattern.

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

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