8285470: Improve handling of @inheritdoc

Reviewed-by: jjg

Author: Pavel Rappo

src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/DocFilesHandlerImpl.java

@@ -199,13 +199,13 @@ private void handleHtmlFile(DocFile srcfile, DocPath dstPath) throws DocFileIOEx
         HtmlDocletWriter docletWriter = new DocFileWriter(configuration, dfilePath, element, pkg);
 
         List<? extends DocTree> localTags = getLocalHeaderTags(utils.getPreamble(dfElement));
-        Content localTagsContent = docletWriter.commentTagsToContent(null, dfElement, localTags, false);
+        Content localTagsContent = docletWriter.commentTagsToContent(dfElement, localTags, false);
 
         String title = getWindowTitle(docletWriter, dfElement).trim();
         HtmlTree htmlContent = docletWriter.getBody(title);
 
         List<? extends DocTree> fullBody = utils.getFullBody(dfElement);
-        Content pageContent = docletWriter.commentTagsToContent(null, dfElement, fullBody, false);
+        Content pageContent = docletWriter.commentTagsToContent(dfElement, fullBody, false);
         docletWriter.addTagsInfo(dfElement, pageContent);
 
         htmlContent.add(new BodyContents()

src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/HtmlDocletWriter.java

@@ -366,9 +366,9 @@ protected boolean hasSerializationOverviewTags(VariableElement field) {
         return !output.isEmpty();
     }
 
-    private Content getInlineTagOutput(Element element, DocTree holder, DocTree tree, TagletWriterImpl.Context context) {
+    private Content getInlineTagOutput(Element element, DocTree tree, TagletWriterImpl.Context context) {
         return getTagletWriterInstance(context)
-                .getInlineTagOutput(element, configuration.tagletManager, holder, tree);
+                .getInlineTagOutput(element, configuration.tagletManager, tree);
     }
 
     /**
@@ -1015,7 +1015,7 @@ public Content seeTagToContent(Element element, DocTree see, TagletWriterImpl.Co
 
         boolean isLinkPlain = kind == LINK_PLAIN;
         Content labelContent = plainOrCode(isLinkPlain,
-                commentTagsToContent(see, element, label, context));
+                commentTagsToContent(element, label, context));
 
         // The signature from the @see tag. We will output this text when a label is not specified.
         Content text = plainOrCode(isLinkPlain,
@@ -1370,7 +1370,7 @@ private void addCommentTags(Element element, List<? extends DocTree> tags, boole
             return;
         }
         Content div;
-        Content result = commentTagsToContent(null, element, tags, first, inSummary);
+        Content result = commentTagsToContent(element, tags, first, inSummary);
         if (depr) {
             div = HtmlTree.DIV(HtmlStyle.deprecationComment, result);
             target.add(div);
@@ -1407,65 +1407,56 @@ boolean ignoreNonInlineTag(DocTree dtree) {
     private boolean commentRemoved = false;
 
     /**
-     * Converts inline tags and text to Content, expanding the
+     * Converts inline tags and text to content, expanding the
      * inline tags along the way.  Called wherever text can contain
      * an inline tag, such as in comments or in free-form text arguments
      * to block tags.
      *
-     * @param holderTag    specific tag where comment resides
-     * @param element    specific element where comment resides
-     * @param tags   array of text tags and inline tags (often alternating)
-               present in the text of interest for this element
-     * @param isFirstSentence  true if text is first sentence
+     * @param element         specific element where comment resides
+     * @param tags            list of text trees and inline tag trees (often alternating)
+     * @param isFirstSentence true if text is first sentence
      * @return a Content object
      */
-    public Content commentTagsToContent(DocTree holderTag,
-                                        Element element,
+    public Content commentTagsToContent(Element element,
                                         List<? extends DocTree> tags,
                                         boolean isFirstSentence)
     {
-        return commentTagsToContent(holderTag, element, tags, isFirstSentence, false);
+        return commentTagsToContent(element, tags, isFirstSentence, false);
     }
 
     /**
-     * Converts inline tags and text to text strings, expanding the
+     * Converts inline tags and text to content, expanding the
      * inline tags along the way.  Called wherever text can contain
      * an inline tag, such as in comments or in free-form text arguments
      * to block tags.
      *
-     * @param holderTag       specific tag where comment resides
      * @param element         specific element where comment resides
-     * @param trees           array of text tags and inline tags (often alternating)
-     *                        present in the text of interest for this element
+     * @param trees           list of text trees and inline tag trees (often alternating)
      * @param isFirstSentence true if text is first sentence
      * @param inSummary       if the comment tags are added into the summary section
      * @return a Content object
      */
-    public Content commentTagsToContent(DocTree holderTag,
-                                        Element element,
+    public Content commentTagsToContent(Element element,
                                         List<? extends DocTree> trees,
                                         boolean isFirstSentence,
                                         boolean inSummary) {
-        return commentTagsToContent(holderTag, element, trees,
+        return commentTagsToContent(element, trees,
                 new TagletWriterImpl.Context(isFirstSentence, inSummary));
     }
 
     /**
-     * Converts inline tags and text to text strings, expanding the
+     * Converts inline tags and text to content, expanding the
      * inline tags along the way.  Called wherever text can contain
      * an inline tag, such as in comments or in free-form text arguments
      * to block tags.
      *
-     * @param holderTag specific tag where comment resides
      * @param element   specific element where comment resides
      * @param trees     list of text trees and inline tag trees (often alternating)
-     *                  present in the text of interest for this element
      * @param context   the enclosing context for the trees
      *
      * @return a Content object
      */
-    public Content commentTagsToContent(DocTree holderTag,
-                                        Element element,
+    public Content commentTagsToContent(Element element,
                                         List<? extends DocTree> trees,
                                         TagletWriterImpl.Context context)
     {
@@ -1576,7 +1567,7 @@ private Content copyDocRootContent(Content content) {
 
                 @Override
                 public Boolean visitDocRoot(DocRootTree node, Content c) {
-                    Content docRootContent = getInlineTagOutput(element, holderTag, node, context);
+                    Content docRootContent = getInlineTagOutput(element, node, context);
                     if (c != null) {
                         c.add(docRootContent);
                     } else {
@@ -1620,15 +1611,15 @@ public Boolean visitErroneous(ErroneousTree node, Content c) {
 
                 @Override
                 public Boolean visitInheritDoc(InheritDocTree node, Content c) {
-                    Content output = getInlineTagOutput(element, holderTag, node, context);
+                    Content output = getInlineTagOutput(element, node, context);
                     result.add(output);
                     // if we obtained the first sentence successfully, nothing more to do
                     return (context.isFirstSentence && !output.isEmpty());
                 }
 
                 @Override
                 public Boolean visitIndex(IndexTree node, Content p) {
-                    Content output = getInlineTagOutput(element, holderTag, node, context);
+                    Content output = getInlineTagOutput(element, node, context);
                     if (output != null) {
                         result.add(output);
                     }
@@ -1643,7 +1634,7 @@ public Boolean visitLink(LinkTree node, Content c) {
                         if (dtp != null) {
                             messages.warning(dtp, "doclet.see.nested_link", "{@" + node.getTagName() + "}");
                         }
-                        Content label = commentTagsToContent(node, element, node.getLabel(), context);
+                        Content label = commentTagsToContent(element, node.getLabel(), context);
                         if (label.isEmpty()) {
                             label = Text.of(node.getReference().getSignature());
                         }
@@ -1686,14 +1677,14 @@ public Boolean visitStartElement(StartElementTree node, Content c) {
 
                 @Override
                 public Boolean visitSummary(SummaryTree node, Content c) {
-                    Content output = getInlineTagOutput(element, holderTag, node, context);
+                    Content output = getInlineTagOutput(element, node, context);
                     result.add(output);
                     return false;
                 }
 
                 @Override
                 public Boolean visitSystemProperty(SystemPropertyTree node, Content p) {
-                    Content output = getInlineTagOutput(element, holderTag, node, context);
+                    Content output = getInlineTagOutput(element, node, context);
                     if (output != null) {
                         result.add(output);
                     }
@@ -1726,7 +1717,7 @@ public Boolean visitText(TextTree node, Content c) {
 
                 @Override
                 protected Boolean defaultAction(DocTree node, Content c) {
-                    Content output = getInlineTagOutput(element, holderTag, node, context);
+                    Content output = getInlineTagOutput(element, node, context);
                     if (output != null) {
                         result.add(output);
                     }

src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/ModuleWriterImpl.java

@@ -346,14 +346,14 @@ public void computeModulesData() {
         utils.getProvidesTrees(mdle).forEach(tree -> {
             TypeElement t = ch.getServiceType(tree);
             if (t != null) {
-                providesTrees.put(t, commentTagsToContent(tree, mdle, ch.getDescription(tree), false, true));
+                providesTrees.put(t, commentTagsToContent(mdle, ch.getDescription(tree), false, true));
             }
         });
         // Generate the map of all services listed using @uses, and the description.
         utils.getUsesTrees(mdle).forEach(tree -> {
             TypeElement t = ch.getServiceType(tree);
             if (t != null) {
-                usesTrees.put(t, commentTagsToContent(tree, mdle, ch.getDescription(tree), false, true));
+                usesTrees.put(t, commentTagsToContent(mdle, ch.getDescription(tree), false, true));
             }
         });
     }

src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/TagletWriterImpl.java

@@ -209,7 +209,7 @@ protected Content indexTagOutput(Element element, IndexTree tag) {
                              .replaceAll("\\s+", " ");
         }
 
-        Content desc = htmlWriter.commentTagsToContent(tag, element, tag.getDescription(), context.within(tag));
+        Content desc = htmlWriter.commentTagsToContent(element, tag.getDescription(), context.within(tag));
         String descText = extractText(desc);
 
         return createAnchorAndSearchIndex(element, tagText, descText, tag);
@@ -298,15 +298,15 @@ public Content paramTagOutput(Element element, ParamTree paramTag, String paramN
         body.add(HtmlTree.CODE(defineID ? HtmlTree.SPAN_ID(HtmlIds.forParam(paramName), nameContent) : nameContent));
         body.add(" - ");
         List<? extends DocTree> description = ch.getDescription(paramTag);
-        body.add(htmlWriter.commentTagsToContent(paramTag, element, description, context.within(paramTag)));
+        body.add(htmlWriter.commentTagsToContent(element, description, context.within(paramTag)));
         return HtmlTree.DD(body);
     }
 
     @Override
     public Content returnTagOutput(Element element, ReturnTree returnTag, boolean inline) {
         CommentHelper ch = utils.getCommentHelper(element);
         List<? extends DocTree> desc = ch.getDescription(returnTag);
-        Content content = htmlWriter.commentTagsToContent(returnTag, element, desc , context.within(returnTag));
+        Content content = htmlWriter.commentTagsToContent(element, desc , context.within(returnTag));
         return inline
                 ? new ContentBuilder(contents.getContent("doclet.Returns_0", content))
                 : new ContentBuilder(HtmlTree.DT(contents.returns), HtmlTree.DD(content));
@@ -366,7 +366,7 @@ public Content simpleBlockTagOutput(Element element, List<? extends DocTree> sim
                 body.add(", ");
             }
             List<? extends DocTree> bodyTags = ch.getBody(simpleTag);
-            body.add(htmlWriter.commentTagsToContent(simpleTag, element, bodyTags, context.within(simpleTag)));
+            body.add(htmlWriter.commentTagsToContent(element, bodyTags, context.within(simpleTag)));
             many = true;
         }
         return new ContentBuilder(
@@ -513,7 +513,7 @@ public Content throwsTagOutput(Element element, ThrowsTree throwsTag, TypeMirror
         }
         body.add(HtmlTree.CODE(excName));
         List<? extends DocTree> description = ch.getDescription(throwsTag);
-        Content desc = htmlWriter.commentTagsToContent(throwsTag, element, description, context.within(throwsTag));
+        Content desc = htmlWriter.commentTagsToContent(element, description, context.within(throwsTag));
         if (desc != null && !desc.isEmpty()) {
             body.add(" - ");
             body.add(desc);
@@ -558,7 +558,7 @@ public Content commentTagsToOutput(Element holder,
                                        List<? extends DocTree> tags,
                                        boolean isFirstSentence)
     {
-        return htmlWriter.commentTagsToContent(holderTag, holder,
+        return htmlWriter.commentTagsToContent(holder,
                 tags, holderTag == null ? context : context.within(holderTag));
     }
 

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

@@ -56,39 +56,34 @@ public InheritDocTaglet() {
     }
 
     /**
-     * Given an element, a {@code DocTree} in the element's doc comment
-     * replace all occurrences of {@code {@inheritDoc}} with documentation from its
-     * superclass or superinterface.
+     * Given an element and {@code @inheritDoc} tag in that element's doc comment,
+     * returns the (recursive) expansion of that tag.
+     *
+     * <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>
      *
      * @param writer the writer that is writing the output.
      * @param e the {@link Element} that we are documenting.
-     *
-     * @param holderTag
-     *
-     * either the tag that holds the {@code {@inheritDoc}} tag or {@code null},
-     * which can mean either of:
-     * <ul>
-     *     <li>the tag is used on a class {@link jdk.javadoc.doclet.Taglet.Location#TYPE} declaration, or
-     *     <li>the tag is used to copy the overall doc comment
-     * </ul>
-     *
+     * @param inheritDoc the {@code {@inheritDoc}} tag
      * @param isFirstSentence true if we only want to inherit the first sentence
      */
     private Content retrieveInheritedDocumentation(TagletWriter writer,
                                                    Element e,
-                                                   DocTree holderTag,
+                                                   DocTree inheritDoc,
                                                    boolean isFirstSentence) {
         Content replacement = writer.getOutputInstance();
         BaseConfiguration configuration = writer.configuration();
         Messages messages = configuration.getMessages();
         Utils utils = configuration.utils;
         CommentHelper ch = utils.getCommentHelper(e);
-        Taglet taglet = holderTag == null
+        var path = ch.getDocTreePath(inheritDoc).getParentPath();
+        DocTree holderTag = path.getLeaf();
+        Taglet taglet = holderTag.getKind() == DocTree.Kind.DOC_COMMENT
                 ? null
                 : configuration.tagletManager.getTaglet(ch.getTagName(holderTag));
         if (taglet != null && !(taglet instanceof InheritableTaglet)) {
             // This tag does not support inheritance.
-            var path = writer.configuration().utils.getCommentHelper(e).getDocTreePath(holderTag);
             messages.warning(path, "doclet.inheritDocWithinInappropriateTag");
             return replacement;
         }
@@ -119,9 +114,7 @@ private Content retrieveInheritedDocumentation(TagletWriter writer,
     }
 
     @Override
-    public Content getInlineTagOutput(Element e, DocTree tag, TagletWriter tagletWriter) {
-        DocTree inheritTag = (tag.getKind() == DocTree.Kind.INHERIT_DOC) ? null : tag;
-        return retrieveInheritedDocumentation(tagletWriter, e,
-                inheritTag, tagletWriter.isFirstSentence);
+    public Content getInlineTagOutput(Element e, DocTree inheritDoc, TagletWriter tagletWriter) {
+        return retrieveInheritedDocumentation(tagletWriter, e, inheritDoc, tagletWriter.isFirstSentence);
     }
 }

src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/toolkit/taglets/TagletWriter.java

@@ -326,15 +326,12 @@ public Content getBlockTagOutput(TagletManager tagletManager,
      *
      * @param holder        the element associated with the doc comment
      * @param tagletManager the taglet manager for the current doclet
-     * @param holderTag     the tag that holds this inline tag, or {@code null} if
-     *                      there is no tag that holds it
      * @param inlineTag     the inline tag to be documented
      *
      * @return the content, or {@code null}
      */
     public Content getInlineTagOutput(Element holder,
                                       TagletManager tagletManager,
-                                      DocTree holderTag,
                                       DocTree inlineTag) {
 
         Map<String, Taglet> inlineTags = tagletManager.getInlineTaglets();
@@ -346,9 +343,7 @@ public Content getInlineTagOutput(Element holder,
         }
 
         try {
-            Content tagletOutput = t.getInlineTagOutput(holder,
-                    holderTag != null && t.getName().equals("inheritDoc") ? holderTag : inlineTag,
-                    this);
+            Content tagletOutput = t.getInlineTagOutput(holder, inlineTag, this);
             tagletManager.seenTag(t.getName());
             return tagletOutput;
         } catch (UnsupportedTagletOperationException e) {

src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/toolkit/util/CommentHelper.java

@@ -711,7 +711,7 @@ private DocTreePath getInheritedDocTreePath(DocTree dtree, ExecutableElement ee)
         DocFinder.Output inheritedDoc =
                 DocFinder.search(configuration,
                         new DocFinder.Input(utils, ee));
-        return inheritedDoc == null || inheritedDoc.holder == ee
+        return inheritedDoc.holder == ee
                 ? null
                 : utils.getCommentHelper(inheritedDoc.holder).getDocTreePath(dtree);
     }