GROOVY-11988: Add support for {@inheritDoc} in external JDK classes#2512
Open
daniellansun wants to merge 1 commit intomasterfrom
Open
GROOVY-11988: Add support for {@inheritDoc} in external JDK classes#2512daniellansun wants to merge 1 commit intomasterfrom
daniellansun wants to merge 1 commit intomasterfrom
Conversation
There was a problem hiding this comment.
Pull request overview
This PR implements GROOVY-11988 by extending groovydoc’s {@inheritDoc} expansion so it can resolve documentation from external JDK classes/interfaces (by reading the local JDK src.zip), and adds regression tests covering common JDK inheritance scenarios (e.g., Writer, Object.clone(), Map).
Changes:
- Add
ExternalJavadocSupportto parse JDK sources fromsrc.zip, materialize externalGroovyMethodDocs, and expand external{@inheritDoc}recursively with cache-session lifecycle management. - Update groovydoc rendering/inheritDoc resolution to better handle external owners and additional inline tags (e.g.,
{@linkplain},{@index}) while rendering. - Add new tests and fixtures verifying external-JDK inheritDoc expansion in generated HTML and verifying cache session behavior.
Reviewed changes
Copilot reviewed 9 out of 9 changed files in this pull request and generated 4 comments.
Show a summary per file
| File | Description |
|---|---|
| subprojects/groovy-groovydoc/src/main/java/org/codehaus/groovy/tools/groovydoc/ExternalJavadocSupport.java | New implementation to load/parse external JDK Javadoc from src.zip, expand {@inheritDoc}, and manage caching via sessions. |
| subprojects/groovy-groovydoc/src/main/java/org/codehaus/groovy/tools/groovydoc/ExternalGroovyClassDoc.java | Enhance external class model (real superclass semantics, interfaces, modifiers, methods via ExternalJavadocSupport). |
| subprojects/groovy-groovydoc/src/main/java/org/codehaus/groovy/tools/groovydoc/GroovyDocTool.java | Wrap render in an external-javadoc cache session so repeated lookups are efficient and then released. |
| subprojects/groovy-groovydoc/src/main/java/org/codehaus/groovy/tools/groovydoc/SimpleGroovyClassDoc.java | Extend internal class resolution to attempt nested-class lookup paths. |
| subprojects/groovy-groovydoc/src/main/java/org/codehaus/groovy/tools/groovydoc/TagRenderer.java | Extend known inline-tag handling and adjust inheritDoc rendering/method matching logic to support external sources. |
| subprojects/groovy-groovydoc/src/test/groovy/org/codehaus/groovy/tools/groovydoc/GroovyDocToolTest.java | Add regression tests for external JDK inheritDoc expansion and cache lifecycle semantics. |
| subprojects/groovy-groovydoc/src/test/groovy/org/codehaus/groovy/tools/groovydoc/testfiles/JavaExtendsWriterInheritDoc.java | Test fixture: {@inheritDoc} inherited from java.io.Writer. |
| subprojects/groovy-groovydoc/src/test/groovy/org/codehaus/groovy/tools/groovydoc/testfiles/JavaObjectCloneInheritDocChild.java | Test fixture: {@inheritDoc} inherited from java.lang.Object#clone. |
| subprojects/groovy-groovydoc/src/test/groovy/org/codehaus/groovy/tools/groovydoc/testfiles/JavaImplementsMapInheritDoc.java | Test fixture: {@inheritDoc} inherited from Map and Object methods. |
Comment on lines
859
to
+871
| String targetClassName = null; | ||
| String nestedBaseName = baseName.replace('.', '$'); | ||
| if (aliases.containsKey(baseName)) { | ||
| targetClassName = aliases.get(baseName); | ||
| } else if (baseName.contains(".")) { | ||
| int dot = baseName.indexOf('.'); | ||
| String outerName = baseName.substring(0, dot); | ||
| String nestedSuffix = baseName.substring(dot).replace('.', '$'); | ||
| if (importName.endsWith("/" + outerName)) { | ||
| targetClassName = importName + nestedSuffix; | ||
| } else if (importName.endsWith("/*")) { | ||
| targetClassName = importName.substring(0, importName.length() - 1) + nestedBaseName; | ||
| } |
Comment on lines
+900
to
+901
| String candidate = baseName.contains(".") ? baseName.replace('.', '$') : baseName; | ||
| return ((SimpleGroovyRootDoc)rootDoc).classNamedExact(pkg + candidate); |
Comment on lines
+905
to
+910
| if (rootDoc == null || fullPathName == null || !fullPathName.contains("$")) return null; | ||
| String nestedSuffix = baseName.replace('.', '$'); | ||
| String current = fullPathName; | ||
| while (current.contains("$")) { | ||
| current = current.substring(0, current.lastIndexOf('$')); | ||
| GroovyClassDoc doc = ((SimpleGroovyRootDoc) rootDoc).classNamedExact(current + "$" + nestedSuffix); |
Comment on lines
969
to
+976
| if (!(memberDoc instanceof GroovyMethodDoc thisMethod)) return null; | ||
| if (classDoc == null) return null; | ||
| if (classDoc == null) return ""; | ||
| if (visited == null) visited = new HashSet<>(); | ||
| if (!visited.add(thisMethod)) return ""; // cycle: suppress literal {@inheritDoc} | ||
|
|
||
| GroovyMethodDoc parent = findInheritedMethod(thisMethod, classDoc, new HashSet<>()); | ||
| if (parent == null) return null; | ||
| if (parent instanceof SimpleGroovyMemberDoc parentMember | ||
| && parentMember.belongsToClass instanceof SimpleGroovyClassDoc parentClassDoc) { | ||
| if (parent == null) return ""; | ||
| if (parent instanceof SimpleGroovyMemberDoc parentMember) { |
Codecov Report❌ Patch coverage is Additional details and impacted files@@ Coverage Diff @@
## master #2512 +/- ##
==================================================
- Coverage 67.3329% 67.3260% -0.0069%
- Complexity 32276 32358 +82
==================================================
Files 1490 1491 +1
Lines 125080 125436 +356
Branches 22525 22631 +106
==================================================
+ Hits 84220 84451 +231
- Misses 33535 33605 +70
- Partials 7325 7380 +55
🚀 New features to boost your workflow:
|
asf-gitbox-commits
force-pushed
the
GROOVY-11988
branch
from
4d79bf4 to
1a2646c
Compare
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
https://issues.apache.org/jira/browse/GROOVY-11988