[lucene-solr] branch LUCENE-9215 updated: LUCENE-9215: add more fixed packages to lucene/core and add some comments.

[rm...@apache.org]

This is an automated email from the ASF dual-hosted git repository.

rmuir pushed a commit to branch LUCENE-9215
in repository https://gitbox.apache.org/repos/asf/lucene-solr.git


The following commit(s) were added to refs/heads/LUCENE-9215 by this push:
     new b853690  LUCENE-9215: add more fixed packages to lucene/core and add some comments.
b853690 is described below

commit b85369090e2a4f2116c639e02070ae4d085404cc
Author: Robert Muir <rm...@apache.org>
AuthorDate: Sun Aug 30 10:13:24 2020 -0400

    LUCENE-9215: add more fixed packages to lucene/core and add some comments.
    
    The previous python tool did recursive file traversal, so the list of
    packages was recursive.
    
    In our case we do exact matching on the package name.
    Add the subpackages too, since they have full documentation and are already fixed.
    
    Also add a few more comments to the linter explaining the hairy parts.
---
 .../src/main/java/org/apache/lucene/gradle/MissingDoclet.java | 11 +++++++++--
 lucene/core/build.gradle                                      | 11 ++++++++++-
 2 files changed, 19 insertions(+), 3 deletions(-)

diff --git a/buildSrc/src/main/java/org/apache/lucene/gradle/MissingDoclet.java b/buildSrc/src/main/java/org/apache/lucene/gradle/MissingDoclet.java
index a797833..413b925 100644
--- a/buildSrc/src/main/java/org/apache/lucene/gradle/MissingDoclet.java
+++ b/buildSrc/src/main/java/org/apache/lucene/gradle/MissingDoclet.java
@@ -39,8 +39,11 @@ import jdk.javadoc.doclet.StandardDoclet;
 /**
  * Checks for missing javadocs, where missing also means "only whitespace" or "license header".
  * Has option --missing-level (package, class, method) so that we can improve over time.
- * Has option --missing-ignore to ignore individual elements (such as split packages).
+ * Has option --missing-ignore to ignore individual elements (such as split packages). 
+ *   It isn't recursive, just ignores exactly the elements you tell it.
+ *   This should be removed when packaging is fixed to no longer be split across JARs.
  * Has option --missing-method to apply "method" level to selected packages (fix one at a time).
+ *   Matches package names exactly: so you'll need to list subpackages separately.
  */
 public class MissingDoclet extends StandardDoclet {
   private static final int PACKAGE = 0;
@@ -222,7 +225,7 @@ public class MissingDoclet extends StandardDoclet {
         if (level(element) >= CLASS) {
           checkComment(element);
           for (var subElement : element.getEnclosedElements()) {
-            // don't check enclosed types, otherwise we'll double-check since they are in the included docTree
+            // don't recurse into enclosed types, otherwise we'll double-check since they are already in the included docTree
             if (subElement.getKind() == ElementKind.METHOD || 
                 subElement.getKind() == ElementKind.CONSTRUCTOR || 
                 subElement.getKind() == ElementKind.FIELD || 
@@ -276,9 +279,13 @@ public class MissingDoclet extends StandardDoclet {
    * that they aren't a license header masquerading as a javadoc comment.
    */
   private void checkComment(Element element) {
+    // sanity check that the element is really "included", because we do some recursion into types
     if (!docEnv.isIncluded(element)) {
       return;
     }
+    // check that this element isn't on our ignore list. This is only used as a workaround for "split packages".
+    // ignoring a package isn't recursive (on purpose), we still check all the classes, etc. inside it.
+    // we just need to cope with the fact module-info.java isn't there because it is split across multiple jars.
     if (ignored.contains(element.toString())) {
       return;
     }
diff --git a/lucene/core/build.gradle b/lucene/core/build.gradle
index 71e1fe5..753cf16 100644
--- a/lucene/core/build.gradle
+++ b/lucene/core/build.gradle
@@ -31,9 +31,18 @@ ext {
   javadocMissingMethod = [
     "org.apache.lucene.util.automaton",
     "org.apache.lucene.analysis",
+    "org.apache.lucene.analysis.standard",
+    "org.apache.lucene.analysis.tokenattributes",
     "org.apache.lucene.document",
     "org.apache.lucene.search.similarities",
     "org.apache.lucene.index",
-    "org.apache.lucene.codecs"
+    "org.apache.lucene.codecs",
+    "org.apache.lucene.codecs.lucene50",
+    "org.apache.lucene.codecs.lucene60",
+    "org.apache.lucene.codecs.lucene80",
+    "org.apache.lucene.codecs.lucene84",
+    "org.apache.lucene.codecs.lucene86",
+    "org.apache.lucene.codecs.lucene87",
+    "org.apache.lucene.codecs.perfield"
   ]
 }