From 02e69d38a4a4b4cdd57b31580154e6621971c27c Mon Sep 17 00:00:00 2001
From: Robert Muir <rmuir@apache.org>
Date: Mon, 24 Feb 2025 18:41:33 -0500
Subject: [PATCH] improve checkJavadocLinks.py to detect "invalid reference"

See background by @mkhludnev on the dev list: https://lists.apache.org/thread/pm1szr9og6qhmjzp371xwk0mvwxxkd1l

In some cases: "invalid reference" is generated, passes through Xdoclint and broken-link checkers, yet links are broken.

Instead of a 404, javadocs seems to emit this in the resulting HTML:

    <details class="invalid-tag">
    <summary>invalid reference</summary>
    <pre>flexible query parser</pre>
    </details

Fix checkJavadocLinks.py to fail the build on these.

Closes #14285
---
 .../check-broken-links/checkJavadocLinks.py          | 12 +++++++++---
 1 file changed, 9 insertions(+), 3 deletions(-)

diff --git a/gradle/documentation/check-broken-links/checkJavadocLinks.py b/gradle/documentation/check-broken-links/checkJavadocLinks.py
index 56dffc8ac41f..edd513eba668 100644
--- a/gradle/documentation/check-broken-links/checkJavadocLinks.py
+++ b/gradle/documentation/check-broken-links/checkJavadocLinks.py
@@ -39,6 +39,12 @@ def __init__(self, baseURL):
     self.printed = False
 
   def handle_starttag(self, tag, attrs):
+    # look for explicit broken link
+    if tag == 'details':
+      for attName, attValue in attrs:
+        if attName == 'class' and attValue == 'invalid-tag':
+          raise RuntimeError('javadoc generated an invalid-tag')
+
     # NOTE: I don't think 'a' should be in here. But try debugging 
     # NumericRangeQuery.html. (Could be javadocs bug, it's a generic type...)
     if tag not in ('link', 'meta', 'frame', 'br', 'wbr', 'hr', 'p', 'li', 'img', 'col', 'a', 'dt', 'dd', 'input'):
@@ -108,7 +114,7 @@ def parse(baseURL, html):
   try:
     parser.feed(html)
     parser.close()
-  except:
+  except Exception:
     # TODO: Python's html.parser is now always lenient, which is no good for us: we want correct HTML in our javadocs
     parser.printFile()
     print('  WARNING: failed to parse %s:' % baseURL)
@@ -140,7 +146,7 @@ def checkAll(dirName):
   else:
     iter = os.walk(dirName)
 
-  for root, dirs, files in iter:
+  for root, _, files in iter:
     for f in files:
       main, ext = os.path.splitext(f)
       ext = ext.lower()
@@ -162,7 +168,7 @@ def checkAll(dirName):
   # ... then verify:
   print()
   print('Verify...')
-  for fullPath, (links, anchors) in allFiles.items():
+  for fullPath, (links, _) in allFiles.items():
     #print fullPath
     printed = False
     for link in links: