[
https://issues.apache.org/jira/browse/SOLR-18523?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel&focusedCommentId=18125319#comment-18125319
]
Nick Shanin commented on SOLR-18523:
------------------------------------
🤖 _AI text below_ 🤖 _(posted on behalf of Nick Shanin)_
I picked this up. A PR is open and ready for review: [PR
#5062|[https://github.com/apache/solr/pull/5062]].
What it does: deletes \{{checkJavadocLinks.py}} and the
\{{check-broken-links.gradle}} wiring, and makes \{{:solr:documentation:check}}
build the documentation only on CI, the gate Lucene used in
[apache/lucene#14905|[https://github.com/apache/lucene/pull/14905]].
Two measurements on the ticket's open questions:
 * A full-tree \{{compileJava}} with DocLint \{{reference}} checks widened to
all scopes passes with 0 failing references, so no source fixes were needed.
 * The \{{missing}} group stays off. Turned on at the shipped scope it reports
22,710 diagnostics, which looks like a separate tree-wide effort; the PR names
it in its Limits instead of including it.
One trade the PR names openly: the crawl also validated fragment anchors on the
pages it scanned, and that checking goes away with it. Anchor validation as its
own check is a follow-up I can do if it is wanted.
The companion half for SOLR-18119, the \{{changes2html.py}} port, is also open
and ready: [PR #5061|[https://github.com/apache/solr/pull/5061]]. The two touch
different files and can merge in either order.
> build: javadoc validation: switch to DocLint
> --------------------------------------------
>
> Key: SOLR-18523
> URL: https://issues.apache.org/jira/browse/SOLR-18523
> Project: Solr
> Issue Type: Task
> Components: Build
> Reporter: David Smiley
> Priority: Major
> Labels: pull-request-available
> Time Spent: 10m
> Remaining Estimate: 0h
>
> Copying a PR description from Apache Lucene
> #[14905|https://github.com/apache/lucene/pull/14905] written by Robert Muir:
> Previously, we validated javadocs by generating 8,000+ html files, then
> recursively crawling them with a python script and looked for broken links.
> This script will no longer find problems, due to how javadocs works.
> Instead, DocLint in javac, especially {{reference}} checks, will fail at
> compile-time if an invalid reference is created, rather than create a broken
> link. This is nice because it does not require creating thousands of files to
> validate what we want.
> {code:java}
> * What went wrong:
> Execution failed for task ':lucene:core:compileJava'.
> > Compilation failed; see the compiler output below.
>
> /home/rmuir/workspace/lucene/lucene/core/src/java/org/apache/lucene/index/IndexWriter.java:174:
> error: reference not found
> * This is a broken link: {@link #bogusReference}
> ^
> Note: Recompile with -Xlint:deprecation for details.
> Note: Some input files use or override a deprecated API.
> 1 error
> {code}
> Valid, but not-visible references from javadocs also no longer create broken
> links: instead the javadoc tool treats them as if they were
> {{{}@linkplain{}}}.
> {code:html}
> This is a broken link: <code>deleterIsPrivate</code>
> {code}
> We did hit a rare bug before, where javadocs generated an {{invalid-tag}} and
> we hacked the script to detect it, but it was just a bug:
> [https://bugs.openjdk.org/browse/JDK-8202617]
> No longer crawling thousands of html files has a great benefit for {{gradle
> check}} development workflow, it means we no longer have to generate them,
> either.
> This saves large amounts of time from {{{}gradle check{}}}, which is wasted:
> we could be using it instead to find actual problems instead of long-tail
> problems.
> To be especially cautious, this PR still causes CI builds {{check}} to depend
> upon {{documentation}} in order to detect rare corner cases:
> * invalid references in overview.html (only 'javadoc' knows these)
> * problems in build machinery itself (e.g. gradle). There's some comfort in
> knowing the thousands of files get created, I guess.
> On my computer, doing {{{}gradlew check -x test{}}}:
> Before: {{BUILD SUCCESSFUL in 4m 33s}}
> After: {{BUILD SUCCESSFUL in 2m 41s}}
--
This message was sent by Atlassian Jira
(v8.20.10#820010)
---------------------------------------------------------------------
To unsubscribe, e-mail: [email protected]
For additional commands, e-mail: [email protected]
