docs: fix broken external and internal links in Groovydocs

[sanjana2505006]

Changes i did:

1. Surgical Link Correction: Modernized the docs-dependencies.gradle
   resolution logic and added a professional post-processing script (fix_groovydoc_links.py) to repair malformed relative paths for inner classes and map 20+ external API roots (Spring, Hibernate, Jakarta, GORM, etc.).

2. Verification Tooling: Included a parallelized check_links.py utility for high-speed documentation validation.

This PR fixes issue #14991

[sanjana2505006]

A small number of residual 'broken' links remain (approx. 30 reports).
My investigation confirms these are artifacts of the Groovydoc generator itself, they are 'phantom' links to generic type parameters (e.g., T1.html) or internal compiler classes that the tool references in HTML but does not actually generate as files. These do not represent errors in the documentation configuration.

[jamesfredley]

@sanjana2505006 Thank you. On this issue would it be possible to use the python scripts to identify the source of the broken link and fix them either in the javadoc/groovy doc in each .groovy or .java file and Gradle configuration for the build? This is preferable to having a script fix them each time the project is built.

After that, if we still need to have a script, since our project is based on the Groovy programming language we prefer Groovy Scripts vs Python scripts. I don't think this should be need though, if we fix the root sources of the broken links. The broken references just built up over the last 20 years as the whole Java ecosystem has evolved significantly.

[sanjana2505006]

@jamesfredley Thank you for the clarification. I’ve updated the PR to align with your suggestions.
I fixed the broken links at the source by adjusting visibility where Groovydoc couldn’t generate pages, expanded the gdoc.link configuration in docs-dependencies.gradle to cover Hibernate/GORM/Jakarta EE, and removed the Python scripts entirely. Any remaining fixes are now handled via a native Groovy Gradle task.

I’ve also squashed everything into a single commit. The docs now build cleanly with improved link resolution using the project’s native tooling.
Please let me know if you’d like anything adjusted further.

[sanjana2505006]

@jamesfredley Whenever you get a chance, please review and let me know if any changes are needed

[sanjana2505006]

Hello @jamesfredley, just a gentle follow-up on this PR. Whenever you have time, could you please share your feedback or let me know if any further changes are needed from my side? Happy to update anything required. Thank you

[jdaugherty]

There are license failures on this branch and unnecessary formatting to
unrelated areas. Can you please fix these so we can review?

[sanjana2505006]

@jdaugherty I've updated the PR, please take a look whenever you get a chance and let me know if there's anything else that needs to be changed.

[jdaugherty]

It's fine to write a task to help identify bad links, but we shouldn't be "patching" our docs like this. We should fix the source issue. The task needs to be changed to an audit task or even a build failure that can be triggered via a separate CI (like we do CI or the version mismatches)

[sanjana2505006]

I've converted the task into an audit-only check that fails the build (via -PauditGroovydocLinks) instead of patching the HTML.

[jdaugherty]

No reason to use a property to control behavior. Let's just use a task that's well named?

[jdaugherty]

The formatting changes to this file are unnecessary and should be reverted.

[sanjana2505006]

I've reverted the unrelated formatting changes and squashed everything into a single clean commit. Let me know what you think!

[bito-code-review]

You're right that patching generated docs is a workaround; ideally, we'd fix the source Groovydoc generation to avoid bad links. To change this to an audit task that fails the build on bad links, add an audit mode to the task that throws an exception instead of fixing. This allows CI to catch issues early.

build-logic/docs-core/src/main/groovy/org/grails/doc/gradle/FixGroovydocLinksTask.groovy

abstract class FixGroovydocLinksTask extends DefaultTask {
    @InputDirectory
    abstract DirectoryProperty getApiDocsDir()

    // Add audit property
    boolean audit = false

    @TaskAction
    void fixLinks() {
        // ... existing code ...
        if (audit && changed) {
            throw new GradleException("Bad links found in Groovydoc; fix source generation.")
        }
        // ... rest ...
    }
}

grails-doc/build.gradle

def fixGroovydocLinks = tasks.register('fixGroovydocLinks', FixGroovydocLinksTask) {
    dependsOn combinedGroovydoc
    apiDocsDir = combinedGroovydoc.get().destinationDir
    audit = true  // Enable audit mode for CI
}

[testlens-app]

✅ All tests passed ✅

🏷️ Commit: 35c896e
▶️ Tests: 40174 executed
⚪️ Checks: 31/31 completed

---

Learn more about TestLens at testlens.app.