You are viewing a plain text version of this content. The canonical link for it is here.
Posted to issues@lucene.apache.org by "ASF subversion and git services (Jira)" <ji...@apache.org> on 2020/08/30 04:02:00 UTC
[jira] [Commented] (LUCENE-9215) replace checkJavaDocs.py with
doclet
[ https://issues.apache.org/jira/browse/LUCENE-9215?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel&focusedCommentId=17187134#comment-17187134 ]
ASF subversion and git services commented on LUCENE-9215:
---------------------------------------------------------
Commit 19cae4218ff605366dbae53011265c8a29add3be in lucene-solr's branch refs/heads/LUCENE-9215 from Robert Muir
[ https://gitbox.apache.org/repos/asf?p=lucene-solr.git;h=19cae42 ]
LUCENE-9215: replace checkJavaDocs.py with doclet
This has the same logic as the previous python, but no longer relies
upon parsing HTML output, instead using java's doclet processor.
The errors are reported like "normal" javadoc errors with source file
name and line number and happen when running "gradlew javadoc"
Although the "rules" are the same as the previous python, the python had
some bugs where the checker didn't quite do exactly what we wanted, so
some fixes were applied throughout.
> replace checkJavaDocs.py with doclet
> ------------------------------------
>
> Key: LUCENE-9215
> URL: https://issues.apache.org/jira/browse/LUCENE-9215
> Project: Lucene - Core
> Issue Type: Task
> Reporter: Robert Muir
> Priority: Major
> Attachments: LUCENE-9215_prototype.patch
>
>
> The current checker runs regular expressions against html, and it breaks when newer java change html output. This is not particularly fun to fix: see LUCENE-9213
> Java releases often now, and when i compared generated html of a simple class across 11,12,13 it surprised me how much changes. So I think we want to avoid parsing their HTML.
> Javadoc {{Xdoclint}} feature has a "missing checker": but it is black/white. Either everything is fully documented or its not. And while you can enable/disable doclint checks per-package, this also seems black/white (either all checks or no checks at all).
> On the other hand the python checker is able to check per-package at different granularities (package, class, method). It makes it possible to iteratively improve the situation.
> With doclet api we could implement checks in pure java, for example to match checkJavaDocs.py logic:
> {code}
> private void checkComment(Element element) {
> var tree = docTrees.getDocCommentTree(element);
> if (tree == null) {
> error(element, "javadocs are missing");
> } else {
> var normalized = tree.getFirstSentence().get(0).toString()
> .replace('\u00A0', ' ')
> .trim()
> .toLowerCase(Locale.ROOT);
> if (normalized.isEmpty()) {
> error(element, "blank javadoc comment");
> } else if (normalized.startsWith("licensed to the apache software foundation") ||
> normalized.startsWith("copyright 2004 the apache software foundation")) {
> error(element, "comment is really a license");
> }
> }
> {code}
> If there are problems then they just appear as errors from the output of {{javadoc}} like usual:
> {noformat}
> javadoc: error - org.apache.lucene.nodoc (package): javadocs are missing
> /home/rmuir/workspace/lucene-solr/lucene/core/src/java/org/apache/lucene/search/spans/SpanNearQuery.java:190: error - SpanNearWeight (class): javadocs are missing
> /home/rmuir/workspace/lucene-solr/lucene/core/src/java/org/apache/lucene/search/spans/SpanContainingQuery.java:54: error - SpanContainingWeight (class): javadocs are missing
> /home/rmuir/workspace/lucene-solr/lucene/core/src/java/org/apache/lucene/search/spans/SpanWithinQuery.java:55: error - SpanWithinWeight (class): javadocs are missing
> /home/rmuir/workspace/lucene-solr/lucene/core/src/java/org/apache/lucene/search/spans/SpanTermQuery.java:94: error - SpanTermWeight (class): javadocs are missing
> /home/rmuir/workspace/lucene-solr/lucene/core/src/java/org/apache/lucene/search/spans/SpanNotQuery.java:109: error - SpanNotWeight (class): javadocs are missing
> /home/rmuir/workspace/lucene-solr/lucene/core/src/java/org/apache/lucene/search/spans/SpanOrQuery.java:139: error - SpanOrWeight (class): javadocs are missing
> /home/rmuir/workspace/lucene-solr/lucene/core/src/java/org/apache/lucene/search/spans/SpanPositionCheckQuery.java:77: error - SpanPositionCheckWeight (class): javadocs are missing
> /home/rmuir/workspace/lucene-solr/lucene/core/src/java/org/apache/lucene/search/MultiCollectorManager.java:61: error - Collectors (class): javadocs are missing
> /home/rmuir/workspace/lucene-solr/lucene/core/src/java/org/apache/lucene/search/MultiCollectorManager.java:89: error - LeafCollectors (class): javadocs are missing
> /home/rmuir/workspace/lucene-solr/lucene/core/src/java/org/apache/lucene/util/PagedBytes.java:353: error - PagedBytesDataOutput (class): javadocs are missing
> /home/rmuir/workspace/lucene-solr/lucene/core/src/java/org/apache/lucene/util/PagedBytes.java:285: error - PagedBytesDataInput (class): javadocs are missing
> /home/rmuir/workspace/lucene-solr/lucene/core/src/java/org/apache/lucene/nodoc/EmptyDoc.java:22: error - EmptyDoc (class): javadocs are missing
> /home/rmuir/workspace/lucene-solr/lucene/core/src/java/org/apache/lucene/nodoc/LicenseDoc.java:36: error - LicenseDoc (class): comment is really a license
> /home/rmuir/workspace/lucene-solr/lucene/core/src/java/org/apache/lucene/nodoc/NoDoc.java:19: error - NoDoc (class): javadocs are missing
> FAILURE: Build failed with an exception.
> * What went wrong:
> Execution failed for task ':lucene:core:javadoc'.
> > Javadoc generation failed. Generated Javadoc options file (useful for troubleshooting): '/home/rmuir/workspace/lucene-solr/lucene/core/build/tmp/javadoc/javadoc.options'
> {noformat}
--
This message was sent by Atlassian Jira
(v8.3.4#803005)
---------------------------------------------------------------------
To unsubscribe, e-mail: issues-unsubscribe@lucene.apache.org
For additional commands, e-mail: issues-help@lucene.apache.org