Refine @inheritDoc support in Groovydoc

Author: daniellansun

subprojects/groovy-groovydoc/src/main/java/org/codehaus/groovy/tools/groovydoc/TagRenderer.java

@@ -75,6 +75,10 @@
  *       not yet implemented — stage 3 of GROOVY-11938.</li>
  *   <li>Client-side syntax highlighting assets (Prism.js / highlight.js)
  *       not yet wired in — stage 4 of GROOVY-11938.</li>
+ *   <li>{@code {@inheritDoc}} inherits the full parent comment rather than
+ *       position-aware substitution inside specific block tags (e.g.
+ *       {@code @param x {@inheritDoc}} inheriting just the parent's
+ *       {@code @param x}). Reasonable initial implementation.</li>
  *   <li>JEP 467 Markdown reference links — GROOVY-11542, pending.</li>
  * </ul>
  *

subprojects/groovy-groovydoc/src/main/java/org/codehaus/groovy/tools/groovydoc/antlr4/GroovydocJavaVisitor.java

@@ -128,6 +128,7 @@ private List<String> getImports() {
      */
     @Override
     public void visit(EnumDeclaration n, Object arg) {
+        if (shouldSkipTypeDeclaration(n)) return;
         SimpleGroovyClassDoc parent = visit(n);
         currentClassDoc.setTokenType(SimpleGroovyDoc.ENUM_DEF);
         super.visit(n, arg);
@@ -161,6 +162,7 @@ public void visit(EnumConstantDeclaration n, Object arg) {
      */
     @Override
     public void visit(AnnotationDeclaration n, Object arg) {
+        if (shouldSkipTypeDeclaration(n)) return;
         SimpleGroovyClassDoc parent = visit(n);
         currentClassDoc.setTokenType(SimpleGroovyDoc.ANNOTATION_DEF);
         super.visit(n, arg);
@@ -201,6 +203,7 @@ public void visit(AnnotationMemberDeclaration n, Object arg) {
      */
     @Override
     public void visit(ClassOrInterfaceDeclaration n, Object arg) {
+        if (shouldSkipTypeDeclaration(n)) return;
         SimpleGroovyClassDoc parent = visit(n);
         if (n.isInterface()) {
             currentClassDoc.setTokenType(SimpleGroovyDoc.INTERFACE_DEF);
@@ -231,6 +234,7 @@ public void visit(ClassOrInterfaceDeclaration n, Object arg) {
      */
     @Override
     public void visit(final RecordDeclaration n, final Object arg) {
+        if (shouldSkipTypeDeclaration(n)) return;
         SimpleGroovyClassDoc parent = visit(n);
         if (n.isRecordDeclaration()) {
             currentClassDoc.setTokenType(SimpleGroovyDoc.RECORD_DEF);
@@ -265,6 +269,10 @@ private String genericTypesAsString(NodeList<TypeParameter> typeParameters) {
         return "<" + DefaultGroovyMethods.join(typeParameters, ", ") + ">";
     }
 
+    private static boolean shouldSkipTypeDeclaration(TypeDeclaration<?> n) {
+        return !n.isTopLevelType() && !n.isNestedType();
+    }
+
     private SimpleGroovyClassDoc visit(TypeDeclaration<?> n) {
         SimpleGroovyClassDoc parent = null;
         List<String> imports = getImports();

subprojects/groovy-groovydoc/src/test/groovy/org/codehaus/groovy/tools/groovydoc/GroovyDocToolTest.java

@@ -24,6 +24,7 @@
 import groovy.test.GroovyTestCase;
 import org.codehaus.groovy.groovydoc.GroovyClassDoc;
 import org.codehaus.groovy.groovydoc.GroovyMethodDoc;
+import org.codehaus.groovy.groovydoc.GroovyParameter;
 import org.codehaus.groovy.groovydoc.GroovyRootDoc;
 import org.codehaus.groovy.runtime.StringGroovyMethods;
 import org.codehaus.groovy.tools.groovydoc.antlr4.GroovyDocParser;
@@ -512,7 +513,7 @@ public void testInheritDocSubstitutesMatchingParentBlockTagsInGroovy() throws Ex
 
     public void testInheritDocSubstitutesMatchingParentBlockTagsInJava() throws Exception {
         String base = "org/codehaus/groovy/tools/groovydoc/testfiles";
-        htmlTool.add(List.of(base + "/JavaInheritDocTagChild.java"));
+        htmlTool.add(List.of(base + "/JavaInheritDocTagBase.java", base + "/JavaInheritDocTagChild.java"));
 
         MockOutputTool output = new MockOutputTool();
         htmlTool.renderToOutput(output, MOCK_DIR);
@@ -559,7 +560,7 @@ public void testInheritDocPreservesSurroundingTextAndExceptionTagsInGroovy() thr
 
     public void testInheritDocPreservesSurroundingTextAndExceptionTagsInJava() throws Exception {
         String base = "org/codehaus/groovy/tools/groovydoc/testfiles";
-        htmlTool.add(List.of(base + "/JavaInheritDocRichTagChild.java"));
+        htmlTool.add(List.of(base + "/JavaInheritDocRichTagBase.java", base + "/JavaInheritDocRichTagChild.java"));
 
         MockOutputTool output = new MockOutputTool();
         htmlTool.renderToOutput(output, MOCK_DIR);
@@ -583,6 +584,63 @@ public void testInheritDocPreservesSurroundingTextAndExceptionTagsInJava() throw
                 doc.contains("{@inheritDoc}"));
     }
 
+    public void testInheritDocResolvesForJavaLocalClassRegressionAtRootDocLevel() throws Exception {
+        String base = "org/codehaus/groovy/tools/groovydoc/testfiles";
+        htmlTool.add(List.of(base + "/JavaLocalClassInheritDocBase.java", base + "/JavaLocalClassInheritDocChild.java"));
+
+        SimpleGroovyRootDoc rootDoc = (SimpleGroovyRootDoc) htmlTool.getRootDoc();
+        GroovyClassDoc childClass = rootDoc.classNamedExact(base + "/JavaLocalClassInheritDocChild");
+        GroovyClassDoc baseClass = rootDoc.classNamedExact(base + "/JavaLocalClassInheritDocBase");
+        assertNotNull("Expected JavaLocalClassInheritDocChild in root doc", childClass);
+        assertNotNull("Expected JavaLocalClassInheritDocBase in root doc", baseClass);
+        assertNull("Local helper class LocalMixinMethodTracker should not become a top-level doc node",
+                rootDoc.classNamedExact(base + "/LocalMixinMethodTracker"));
+        assertEquals("Expected JavaLocalClassInheritDocChild to resolve JavaLocalClassInheritDocBase as its superclass",
+                base + "/JavaLocalClassInheritDocBase", childClass.superclass().getFullPathName());
+
+        GroovyMethodDoc child = findMethod(childClass, "findMixinMethod", 2);
+        GroovyMethodDoc parent = findMethod(baseClass, "findMixinMethod", 2);
+        assertNotNull("Expected JavaLocalClassInheritDocChild.findMixinMethod in root doc. Available candidates: "
+                + describeMethods(childClass, "findMixinMethod"), child);
+        assertNotNull("Expected JavaLocalClassInheritDocBase.findMixinMethod in root doc. Available candidates: "
+                + describeMethods(baseClass, "findMixinMethod") + ". Anywhere in root: "
+                + describeClassesWithMethod(rootDoc, "findMixinMethod"), parent);
+
+        String childComment = normalizeWhitespace(child.commentText());
+        assertTrue("Expected inherited first sentence on JavaLocalClassInheritDocChild.findMixinMethod.\nchild="
+                        + describeMethod(child) + "\nparent=" + describeMethod(parent) + "\ncomment=" + child.commentText(),
+                childComment.contains("Searches for a matching mixin method."));
+        assertTrue("Expected inherited return description on JavaLocalClassInheritDocChild.findMixinMethod.\nchild="
+                        + describeMethod(child) + "\nparent=" + describeMethod(parent) + "\ncomment=" + child.commentText(),
+                childComment.contains("the matching mixin method, or <CODE>null</CODE> if none is found"));
+        assertFalse("JavaLocalClassInheritDocChild.findMixinMethod should not keep literal inheritDoc in commentText.\nchild="
+                        + describeMethod(child) + "\nparent=" + describeMethod(parent) + "\ncomment=" + child.commentText(),
+                child.commentText().contains("{@inheritDoc}"));
+    }
+
+    public void testInheritDocResolvesForJavaLocalClassRegressionInHtml() throws Exception {
+        String base = "org/codehaus/groovy/tools/groovydoc/testfiles";
+        htmlTool.add(List.of(base + "/JavaLocalClassInheritDocBase.java", base + "/JavaLocalClassInheritDocChild.java"));
+        MockOutputTool output = new MockOutputTool();
+        htmlTool.renderToOutput(output, MOCK_DIR);
+
+        String doc = output.getText(MOCK_DIR + "/" + base + "/JavaLocalClassInheritDocChild.html");
+        String methodSection = substringBetween(doc,
+                "<a name=\"findMixinMethod(java.lang.String, java.lang.Class)\"><!-- --></a>",
+                "<!-- ========= END OF CLASS DATA ========= -->");
+        String normalized = normalizeWhitespace(methodSection);
+        assertNotNull("Expected JavaLocalClassInheritDocChild.html in output", doc);
+        assertNull("Local helper class LocalMixinMethodTracker should not get its own HTML page",
+                output.getText(MOCK_DIR + "/" + base + "/LocalMixinMethodTracker.html"));
+        assertNotNull("Expected a dedicated HTML section for JavaLocalClassInheritDocChild.findMixinMethod:\n" + doc, methodSection);
+        assertTrue("Expected inherited summary in JavaLocalClassInheritDocChild.findMixinMethod HTML:\n" + doc,
+                normalized.contains("Searches for a matching mixin method."));
+        assertTrue("Expected inherited return text in JavaLocalClassInheritDocChild.findMixinMethod HTML:\n" + doc,
+                normalized.contains("the matching mixin method, or <CODE>null</CODE> if none is found"));
+        assertFalse("JavaLocalClassInheritDocChild.findMixinMethod HTML should not keep literal inheritDoc:\n" + doc,
+                methodSection.contains("{@inheritDoc}"));
+    }
+
     // Cyclic inheritDoc references must collapse safely instead of
     // recursing until the renderer overflows the stack.
     public void testInheritDocCycleDoesNotOverflow() throws Exception {
@@ -658,6 +716,46 @@ private static String normalizeWhitespace(String text) {
         return text == null ? null : text.replaceAll("\\s+", " ").trim();
     }
 
+    private static GroovyMethodDoc findMethod(GroovyClassDoc classDoc, String name, int parameterCount) {
+        for (GroovyMethodDoc method : classDoc.methods()) {
+            if (name.equals(method.name()) && method.parameters().length == parameterCount) {
+                return method;
+            }
+        }
+        return null;
+    }
+
+    private static String describeMethod(GroovyMethodDoc method) {
+        if (method == null) return "null";
+        String owner = method.containingClass() == null ? "<no-owner>" : method.containingClass().qualifiedTypeName();
+        return owner + "#" + method.name() + "("
+                + Arrays.stream(method.parameters()).map(GroovyParameter::typeName).collect(Collectors.joining(", "))
+                + ")";
+    }
+
+    private static String describeMethods(GroovyClassDoc classDoc, String name) {
+        return Arrays.stream(classDoc.methods())
+                .filter(method -> name.equals(method.name()))
+                .map(GroovyDocToolTest::describeMethod)
+                .collect(Collectors.joining("; "));
+    }
+
+    private static String describeClassesWithMethod(GroovyRootDoc rootDoc, String name) {
+        return Arrays.stream(rootDoc.classes())
+                .map(classDoc -> classDoc.getFullPathName() + ": " + describeMethods(classDoc, name))
+                .filter(s -> !s.endsWith(": "))
+                .collect(Collectors.joining(" | "));
+    }
+
+    private static String substringBetween(String text, String startMarker, String endMarker) {
+        if (text == null) return null;
+        int start = text.indexOf(startMarker);
+        if (start < 0) return null;
+        int end = text.indexOf(endMarker, start + startMarker.length());
+        if (end < 0) return text.substring(start);
+        return text.substring(start, end);
+    }
+
     // GROOVY-8025: annotations whose members are closure expressions must
     // not NPE during groovydoc processing. The original bug was in the old
     // SimpleGroovyClassDocAssembler — the refactor to GroovydocVisitor

subprojects/groovy-groovydoc/src/test/groovy/org/codehaus/groovy/tools/groovydoc/testfiles/JavaInheritDocRichTagBase.java

@@ -0,0 +1,35 @@
+/*
+ *  Licensed to the Apache Software Foundation (ASF) under one
+ *  or more contributor license agreements.  See the NOTICE file
+ *  distributed with this work for additional information
+ *  regarding copyright ownership.  The ASF licenses this file
+ *  to you under the Apache License, Version 2.0 (the
+ *  "License"); you may not use this file except in compliance
+ *  with the License.  You may obtain a copy of the License at
+ *
+ *    http://www.apache.org/licenses/LICENSE-2.0
+ *
+ *  Unless required by applicable law or agreed to in writing,
+ *  software distributed under the License is distributed on an
+ *  "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ *  KIND, either express or implied.  See the License for the
+ *  specific language governing permissions and limitations
+ *  under the License.
+ */
+package org.codehaus.groovy.tools.groovydoc.testfiles;
+
+import java.io.IOException;
+
+class JavaInheritDocRichTagBase {
+    /**
+     * Java base transform description that should not leak into block tags.
+     *
+     * @param value java parent parameter description with {@code JAVA_VALUE_TOKEN}
+     * @return java parent return description with {@code JAVA_RETURN_TOKEN}
+     * @throws IllegalArgumentException java parent illegal-argument description with {@code JAVA_BAD_VALUE_TOKEN}
+     * @exception java.io.IOException java parent IO description with {@code JAVA_IO_VALUE_TOKEN}
+     */
+    public String transform(String value) throws IOException {
+        return value.toUpperCase();
+    }
+}

subprojects/groovy-groovydoc/src/test/groovy/org/codehaus/groovy/tools/groovydoc/testfiles/JavaInheritDocRichTagChild.java

@@ -20,20 +20,6 @@
 
 import java.io.IOException;
 
-class JavaInheritDocRichTagBase {
-    /**
-     * Java base transform description that should not leak into block tags.
-     *
-     * @param value java parent parameter description with {@code JAVA_VALUE_TOKEN}
-     * @return java parent return description with {@code JAVA_RETURN_TOKEN}
-     * @throws IllegalArgumentException java parent illegal-argument description with {@code JAVA_BAD_VALUE_TOKEN}
-     * @exception java.io.IOException java parent IO description with {@code JAVA_IO_VALUE_TOKEN}
-     */
-    public String transform(String value) throws IOException {
-        return value.toUpperCase();
-    }
-}
-
 public class JavaInheritDocRichTagChild extends JavaInheritDocRichTagBase {
     /**
      * Java rich child summary.

subprojects/groovy-groovydoc/src/test/groovy/org/codehaus/groovy/tools/groovydoc/testfiles/JavaInheritDocTagBase.java

@@ -0,0 +1,31 @@
+/*
+ *  Licensed to the Apache Software Foundation (ASF) under one
+ *  or more contributor license agreements.  See the NOTICE file
+ *  distributed with this work for additional information
+ *  regarding copyright ownership.  The ASF licenses this file
+ *  to you under the Apache License, Version 2.0 (the
+ *  "License"); you may not use this file except in compliance
+ *  with the License.  You may obtain a copy of the License at
+ *
+ *    http://www.apache.org/licenses/LICENSE-2.0
+ *
+ *  Unless required by applicable law or agreed to in writing,
+ *  software distributed under the License is distributed on an
+ *  "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ *  KIND, either express or implied.  See the License for the
+ *  specific language governing permissions and limitations
+ *  under the License.
+ */
+package org.codehaus.groovy.tools.groovydoc.testfiles;
+
+class JavaInheritDocTagBase {
+    /**
+     * Java base transform description.
+     *
+     * @param value java parent parameter description
+     * @return java parent return description
+     */
+    public String transform(String value) {
+        return value.toUpperCase();
+    }
+}

subprojects/groovy-groovydoc/src/test/groovy/org/codehaus/groovy/tools/groovydoc/testfiles/JavaInheritDocTagChild.java

@@ -18,18 +18,6 @@
  */
 package org.codehaus.groovy.tools.groovydoc.testfiles;
 
-class JavaInheritDocTagBase {
-    /**
-     * Java base transform description.
-     *
-     * @param value java parent parameter description
-     * @return java parent return description
-     */
-    public String transform(String value) {
-        return value.toUpperCase();
-    }
-}
-
 public class JavaInheritDocTagChild extends JavaInheritDocTagBase {
     /**
      * Java child summary.

subprojects/groovy-groovydoc/src/test/groovy/org/codehaus/groovy/tools/groovydoc/testfiles/JavaLocalClassInheritDocBase.java

@@ -0,0 +1,41 @@
+/*
+ *  Licensed to the Apache Software Foundation (ASF) under one
+ *  or more contributor license agreements.  See the NOTICE file
+ *  distributed with this work for additional information
+ *  regarding copyright ownership.  The ASF licenses this file
+ *  to you under the Apache License, Version 2.0 (the
+ *  "License"); you may not use this file except in compliance
+ *  with the License.  You may obtain a copy of the License at
+ *
+ *    http://www.apache.org/licenses/LICENSE-2.0
+ *
+ *  Unless required by applicable law or agreed to in writing,
+ *  software distributed under the License is distributed on an
+ *  "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ *  KIND, either express or implied.  See the License for the
+ *  specific language governing permissions and limitations
+ *  under the License.
+ */
+package org.codehaus.groovy.tools.groovydoc.testfiles;
+
+class JavaLocalClassInheritDocBase {
+    void prepareMixinMethods() {
+        class LocalMixinMethodTracker {
+            void record() {
+            }
+        }
+
+        new LocalMixinMethodTracker().record();
+    }
+
+    /**
+     * Searches for a matching mixin method.
+     *
+     * @param methodName the method name
+     * @param arguments the parameter types
+     * @return the matching mixin method, or {@code null} if none is found
+     */
+    protected Object findMixinMethod(String methodName, Class[] arguments) {
+        return null;
+    }
+}

subprojects/groovy-groovydoc/src/test/groovy/org/codehaus/groovy/tools/groovydoc/testfiles/JavaLocalClassInheritDocChild.java

@@ -0,0 +1,27 @@
+/*
+ *  Licensed to the Apache Software Foundation (ASF) under one
+ *  or more contributor license agreements.  See the NOTICE file
+ *  distributed with this work for additional information
+ *  regarding copyright ownership.  The ASF licenses this file
+ *  to you under the Apache License, Version 2.0 (the
+ *  "License"); you may not use this file except in compliance
+ *  with the License.  You may obtain a copy of the License at
+ *
+ *    http://www.apache.org/licenses/LICENSE-2.0
+ *
+ *  Unless required by applicable law or agreed to in writing,
+ *  software distributed under the License is distributed on an
+ *  "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ *  KIND, either express or implied.  See the License for the
+ *  specific language governing permissions and limitations
+ *  under the License.
+ */
+package org.codehaus.groovy.tools.groovydoc.testfiles;
+
+public class JavaLocalClassInheritDocChild extends JavaLocalClassInheritDocBase {
+    /** {@inheritDoc} */
+    @Override
+    public Object findMixinMethod(String methodName, Class[] arguments) {
+        return null;
+    }
+}