David Smiley created SOLR-18523:
-----------------------------------
Summary: 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
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]
