[
https://issues.apache.org/jira/browse/LUCENE-9215?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel&focusedCommentId=17187258#comment-17187258
]
ASF subversion and git services commented on LUCENE-9215:
---------------------------------------------------------
Commit 2c365f15768af6f4b0835344117ea3e25e054892 in lucene-solr's branch
refs/heads/LUCENE-9215 from Robert Muir
[ https://gitbox.apache.org/repos/asf?p=lucene-solr.git;h=2c365f1 ]
LUCENE-9215: more extensive javadocs checks by default
Add "parameter" which, in addition to the checks done by "method",
validates that there is an @param tag for each formal parameter of a
method/constructor.
This is a good win for an API, documenting the parameters in this way
plugs in nicely into IDEs and users can just hover over things to pop up
precisely what they need to see.
Some modules only require just a few fixes to lock this in, so we should
fix the easy wins at least (I fixed lucene/memory since it literally
only had ONE problem).
> 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
>
> Time Spent: 2h 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-unsubscr...@lucene.apache.org
For additional commands, e-mail: issues-h...@lucene.apache.org
