Apache Lucene open-source search software
Improve MissingDoclet linter to check records correctly (#13332)
Uwe Schindlere6dac3400d7b
diff --git a/dev-tools/missing-doclet/src/main/java/org/apache/lucene/missingdoclet/MissingDoclet.java b/dev-tools/missing-doclet/src/main/java/org/apache/lucene/missingdoclet/MissingDoclet.javaindex ba96ae6b7c7..2b07008ec59 100644--- a/dev-tools/missing-doclet/src/main/java/org/apache/lucene/missingdoclet/MissingDoclet.java+++ b/dev-tools/missing-doclet/src/main/java/org/apache/lucene/missingdoclet/MissingDoclet.java@@ -34,6 +34,7 @@ import javax.lang.model.type.DeclaredType;import javax.lang.model.type.TypeKind;import javax.lang.model.util.ElementFilter;import javax.lang.model.util.Elements;+import javax.lang.model.util.Elements.Origin;import javax.tools.Diagnostic;import com.sun.source.doctree.DocCommentTree;@@ -241,6 +242,9 @@ public class MissingDoclet extends StandardDoclet {case ANNOTATION_TYPE:if (level(element) >= CLASS) {checkComment(element);+ if (element instanceof TypeElement te && element.getKind() == ElementKind.RECORD && level(element) >= METHOD) {+ checkRecordParameters(te, docTrees.getDocCommentTree(element));+ }for (var subElement : element.getEnclosedElements()) {// don't recurse into enclosed types, otherwise we'll double-check since they are already in the included docTreeif (subElement.getKind() == ElementKind.METHOD ||@@ -257,7 +261,7 @@ public class MissingDoclet extends StandardDoclet {case CONSTRUCTOR:case FIELD:case ENUM_CONSTANT:- if (level(element) >= METHOD && !isSyntheticEnumMethod(element)) {+ if (level(element) >= METHOD && !isSyntheticMethod(element)) {checkComment(element);}break;@@ -267,11 +271,20 @@ public class MissingDoclet extends StandardDoclet {}/**- * Return true if the method is synthetic enum method (values/valueOf).- * According to the doctree documentation, the "included" set never includes synthetic elements.+ * Return true if the method is synthetic enum (values/valueOf) or record accessor method.+ * According to the doctree documentation, the "included" set never includes synthetic/mandated elements.* UweSays: It should not happen but it happens!*/- private boolean isSyntheticEnumMethod(Element element) {+ private boolean isSyntheticMethod(Element element) {+ // exclude all not explicitely declared methods+ if (elementUtils.getOrigin(element) != Origin.EXPLICIT) {+ return true;+ }+ // exclude record accessors+ if (element instanceof ExecutableElement ex && elementUtils.recordComponentFor(ex) != null) {+ return true;+ }+ // exclude special enum methodsString simpleName = element.getSimpleName().toString();if (simpleName.equals("values") || simpleName.equals("valueOf")) {if (element.getEnclosingElement().getKind() == ElementKind.ENUM) {@@ -317,8 +330,8 @@ public class MissingDoclet extends StandardDoclet {error(element, "comment is really a license");}}- if (level >= PARAMETER) {- checkParameters(element, tree);+ if (level >= PARAMETER && element instanceof ExecutableElement execEle) {+ checkMethodParameters(execEle, tree);}}@@ -378,25 +391,37 @@ public class MissingDoclet extends StandardDoclet {return result;}+ /** Returns all {@code @param} parameters we see in the javadocs of the element */+ private Set<String> getDocParameters(DocCommentTree tree) {+ return Stream.ofNullable(tree)+ .flatMap(t -> t.getBlockTags().stream())+ .filter(ParamTree.class::isInstance)+ .map(tag -> ((ParamTree)tag).getName().getName().toString())+ .collect(Collectors.toSet());+ }+/** Checks there is a corresponding "param" tag for each method parameter */- private void checkParameters(Element element, DocCommentTree tree) {- if (element instanceof ExecutableElement) {- // record each @param that we see- Set<String> seenParameters = new HashSet<>();- if (tree != null) {- for (var tag : tree.getBlockTags()) {- if (tag instanceof ParamTree) {- var name = ((ParamTree)tag).getName().getName().toString();- seenParameters.add(name);- }- }+ private void checkMethodParameters(ExecutableElement element, DocCommentTree tree) {+ // record each @param that we see+ var seenParameters = getDocParameters(tree);+ // now compare the method's formal parameter list against it+ for (var param : element.getParameters()) {+ var name = param.getSimpleName().toString();+ if (!seenParameters.contains(name)) {+ error(element, "missing javadoc @param for parameter '" + name + "'");}- // now compare the method's formal parameter list against it- for (var param : ((ExecutableElement)element).getParameters()) {- var name = param.getSimpleName().toString();- if (!seenParameters.contains(name)) {- error(element, "missing javadoc @param for parameter '" + name + "'");- }+ }+ }++ /** Checks there is a corresponding "param" tag for each record component */+ private void checkRecordParameters(TypeElement element, DocCommentTree tree) {+ // record each @param that we see+ var seenParameters = getDocParameters(tree);+ // now compare the record components against it+ for (var comp : element.getRecordComponents()) {+ var name = comp.getSimpleName().toString();+ if (!seenParameters.contains(name)) {+ error(element, "missing javadoc @param for record component '" + name + "'");}}}diff --git a/lucene/CHANGES.txt b/lucene/CHANGES.txtindex 51cb9d8a8df..937130f506f 100644--- a/lucene/CHANGES.txt+++ b/lucene/CHANGES.txt@@ -226,6 +226,8 @@ Other* GITHUB#13296: Convert the FieldEntry, a static nested class, into a record. (Sanjay Dutt)+* GITHUB#13332: Improve MissingDoclet linter to check records correctly. (Uwe Schindler)+======================== Lucene 9.11.0 =======================API Changes