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/09/01 16:37: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=17188621#comment-17188621 ]
ASF subversion and git services commented on LUCENE-9215:
---------------------------------------------------------
Commit 10c4c4f034f809149c40c1b7555d37c51ab38417 in lucene-solr's branch refs/heads/LUCENE-9215 from Uwe Schindler
[ https://gitbox.apache.org/repos/asf?p=lucene-solr.git;h=10c4c4f ]
Merge branch 'master' of https://gitbox.apache.org/repos/asf/lucene-solr into LUCENE-9215
# Conflicts:
# gradle/documentation/render-javadoc.gradle
> 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, overrides.patch
>
> Time Spent: 5h 10m
> Remaining Estimate: 0h
>
> 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