RFR: 8283864: Clean up DocFinder and friends

[Jonathan Gibbons]

On Wed, 13 Apr 2022 18:02:14 GMT, Pavel Rappo <prappo at openjdk.org> wrote:

> A clean-up to facilitate more clean-up in the future.

Nice cleanup.  There is one suggestion for a minor change, to eliminate an unnecessary `utils` parameter from `DocFinder.Input.copy`

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

> 44: /**
> 45:  * An inline taglet representing the {@code {@inheritDoc}} tag.
> 46:  * It is used to copy documentation from superclass (but not superinterface)

is that true,(not super interfaces)?

what about when `{@inheritDoc}` is used in interfaces?

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

> 87:                 ? null
> 88:                 : configuration.tagletManager.getTaglet(ch.getTagName(holderTag));
> 89:         if (taglet != null && !(taglet instanceof InheritableTaglet)) {

Optional, this is a possible use case for patterns in `instanceof` ... you could declare a name here and save the cast on line 95

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

> 88:                 : configuration.tagletManager.getTaglet(ch.getTagName(holderTag));
> 89:         if (taglet != null && !(taglet instanceof InheritableTaglet)) {
> 90:             //This tag does not support inheritance.

mild preference for space after `//` similar to lines 104-111

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

> 110:             assert !(e instanceof TypeElement typeElement)
> 111:                     || typeElement.getSuperclass().getKind() == TypeKind.NONE;
> 112:             String message = utils.getSimpleName(e) +

`message` sounds more freeform than the value might imply. I'd be tempted to call it `signature`, and replace the `""` with `e.toString()` (just in case)

src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/toolkit/util/DocFinder.java line 44:

> 42: public class DocFinder {
> 43: 
> 44:     public record DocTreeInfo(DocTree docTree, Element element) { }

nice

src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/toolkit/util/DocFinder.java line 136:

> 134:         }
> 135: 
> 136:         private Input copy(Utils utils) {

Why do you need to pass in `utils` -- you can just use the value in the `Input` object being copied.

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

Marked as reviewed by jjg (Reviewer).

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