[
https://issues.apache.org/jira/browse/SOLR-18523?page=com.atlassian.jira.plugin.system.issuetabpanels:all-tabpanel
]
ASF GitHub Bot updated SOLR-18523:
----------------------------------
Labels: pull-request-available (was: )
> 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]
