rmuir opened a new pull request, #14905:
URL: https://github.com/apache/lucene/pull/14905
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.
```
* 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
```
Valid, but not-visible references from javadocs also no longer create broken
links: instead the javadoc tool treats them as if they were `{@linkplain}`.
```html
This is a broken link: <code>deleterIsPrivate</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 is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: issues-unsubscr...@lucene.apache.org
For queries about this service, please contact Infrastructure at:
us...@infra.apache.org
---------------------------------------------------------------------
To unsubscribe, e-mail: issues-unsubscr...@lucene.apache.org
For additional commands, e-mail: issues-h...@lucene.apache.org
