Improve Javadoc of predicates and functions #912

At the moment it is quite challenging to find a certain predicate or function, because users might need to know the domain model very well to find the necessary location (e.g. predicates like `nameMatching(..)` are defined within `HasName.Predicates` to be reused for everything that has a name, but at the same time users now need to know that `JavaClass` implements `HasName` to use these predicates). While in the long term it might make sense to implement a better entry point API to improve discoverability, for now we can at least improve the documentation to link from more specific predicates to more generic ones. I.e. that I have some chance to discover 1) Javadoc on some method `...That(DescribedPredicate<? super JavaClass>)` -> "you can find predefined predicates in `JavaClass.Predicates` 2) Javadoc on `JavaClass.Predicates` -> "due to inheritance you can find further applicable predicates in `HasName.Predicates`, `HasModifiers.Predicates`, ..."
TNG · Jul 13, 2022 · b3a47b5 · b3a47b5
2 parents 5299db6 + 5a0b1b6
commit b3a47b5
Show file tree

Hide file tree

Showing 49 changed files with 949 additions and 22 deletions.
diff --git a/...est/java/com/tngtech/archunit/lang/syntax/elements/ClassesShouldNewerJavaVersionTest.java b/...est/java/com/tngtech/archunit/lang/syntax/elements/ClassesShouldNewerJavaVersionTest.java
@@ -0,0 +1,64 @@
+package com.tngtech.archunit.lang.syntax.elements;
+
+import com.tngtech.archunit.lang.ArchRule;
+import com.tngtech.archunit.lang.EvaluationResult;
+import com.tngtech.archunit.lang.conditions.ArchConditions;
+import com.tngtech.archunit.lang.syntax.elements.testobjects.SomeRecord;
+import com.tngtech.java.junit.dataprovider.DataProvider;
+import com.tngtech.java.junit.dataprovider.DataProviderRunner;
+import com.tngtech.java.junit.dataprovider.UseDataProvider;
+import org.junit.Test;
+import org.junit.runner.RunWith;
+
+import static com.tngtech.archunit.core.domain.TestUtils.importClasses;
+import static com.tngtech.archunit.lang.syntax.ArchRuleDefinition.classes;
+import static com.tngtech.archunit.lang.syntax.elements.ClassesShouldTest.locationPattern;
+import static com.tngtech.archunit.lang.syntax.elements.ClassesShouldTest.singleLineFailureReportOf;
+import static com.tngtech.archunit.testutil.Assertions.assertThat;
+import static com.tngtech.java.junit.dataprovider.DataProviders.$;
+import static com.tngtech.java.junit.dataprovider.DataProviders.$$;
+import static java.util.regex.Pattern.quote;
+
+@RunWith(DataProviderRunner.class)
+public class ClassesShouldNewerJavaVersionTest {
+
+    @DataProvider
+    public static Object[][] data_beRecords() {
+        return $$(
+                $(classes().should().beRecords(), SomeRecord.class, String.class),
+                $(classes().should(ArchConditions.beRecords()), SomeRecord.class, String.class));
+    }
+
+    @Test
+    @UseDataProvider
+    public void test_beRecords(ArchRule rule, Class<?> satisfied, Class<?> violated) {
+        EvaluationResult result = rule.evaluate(importClasses(satisfied, violated));
+
+        assertThat(singleLineFailureReportOf(result))
+                .contains("classes should be records")
+                .containsPattern(String.format("Class <%s> is no record in %s",
+                        quote(violated.getName()),
+                        locationPattern(violated)))
+                .doesNotMatch(String.format(".*%s.* record.*", quote(satisfied.getName())));
+    }
+
+    @DataProvider
+    public static Object[][] data_notBeRecords() {
+        return $$(
+                $(classes().should().notBeRecords(), String.class, SomeRecord.class),
+                $(classes().should(ArchConditions.notBeRecords()), String.class, SomeRecord.class));
+    }
+
+    @Test
+    @UseDataProvider
+    public void test_notBeRecords(ArchRule rule, Class<?> satisfied, Class<?> violated) {
+        EvaluationResult result = rule.evaluate(importClasses(satisfied, violated));
+
+        assertThat(singleLineFailureReportOf(result))
+                .contains("classes should not be records")
+                .containsPattern(String.format("Class <%s> is a record in %s",
+                        quote(violated.getName()),
+                        locationPattern(violated)))
+                .doesNotMatch(String.format(".*%s.* record.*", quote(satisfied.getName())));
+    }
+}
diff --git a/.../src/jdk16test/java/com/tngtech/archunit/lang/syntax/elements/testobjects/SomeRecord.java b/.../src/jdk16test/java/com/tngtech/archunit/lang/syntax/elements/testobjects/SomeRecord.java
@@ -0,0 +1,4 @@
+package com.tngtech.archunit.lang.syntax.elements.testobjects;
+
+public record SomeRecord(int attribute) {
+}
diff --git a/archunit/src/main/java/com/tngtech/archunit/core/domain/AccessTarget.java b/archunit/src/main/java/com/tngtech/archunit/core/domain/AccessTarget.java
@@ -226,6 +226,9 @@ public String toString() {
         return "target{" + fullName + '}';
     }
 
+    /**
+     * Predefined {@link ChainableFunction functions} to transform {@link AccessTarget}.
+     */
     public static final class Functions {
         private Functions() {
         }
@@ -311,6 +314,9 @@ public String getDescription() {
             return "field <" + getFullName() + ">";
         }
 
+        /**
+         * Predefined {@link ChainableFunction functions} to transform {@link FieldAccessTarget}.
+         */
         public static final class Functions {
             private Functions() {
             }
@@ -390,6 +396,9 @@ public Optional<? extends JavaCodeUnit> resolveMember() {
             return (Optional<? extends JavaCodeUnit>) super.resolveMember();
         }
 
+        /**
+         * Predefined {@link ChainableFunction functions} to transform {@link CodeUnitAccessTarget}.
+         */
         public static final class Functions {
             private Functions() {
             }
@@ -473,6 +482,9 @@ public String getDescription() {
             return "constructor <" + getFullName() + ">";
         }
 
+        /**
+         * Predefined {@link ChainableFunction functions} to transform {@link ConstructorCallTarget}.
+         */
         public static final class Functions {
             private Functions() {
             }
@@ -521,6 +533,9 @@ public String getDescription() {
             return "constructor <" + getFullName() + ">";
         }
 
+        /**
+         * Predefined {@link ChainableFunction functions} to transform {@link ConstructorReferenceTarget}.
+         */
         public static final class Functions {
             private Functions() {
             }
@@ -593,6 +608,9 @@ public String getDescription() {
             return "method <" + getFullName() + ">";
         }
 
+        /**
+         * Predefined {@link ChainableFunction functions} to transform {@link MethodCallTarget}.
+         */
         public static final class Functions {
             private Functions() {
             }
@@ -643,6 +661,9 @@ public String getDescription() {
             return "method <" + getFullName() + ">";
         }
 
+        /**
+         * Predefined {@link ChainableFunction functions} to transform {@link MethodReferenceTarget}.
+         */
         public static final class Functions {
             private Functions() {
             }
@@ -658,6 +679,16 @@ public Optional<JavaMethod> apply(MethodReferenceTarget input) {
         }
     }
 
+    /**
+     * Predefined {@link DescribedPredicate predicates} targeting {@link AccessTarget}.
+     * Note that due to inheritance further predicates for {@link AccessTarget} can be found in the following locations:
+     * <ul>
+     *     <li>{@link HasName.Predicates}</li>
+     *     <li>{@link HasName.AndFullName.Predicates}</li>
+     *     <li>{@link CanBeAnnotated.Predicates}</li>
+     *     <li>{@link HasOwner.Predicates}</li>
+     * </ul>
+     */
     public static final class Predicates {
         private Predicates() {
         }

diff --git a/archunit/src/main/java/com/tngtech/archunit/core/domain/Dependency.java b/archunit/src/main/java/com/tngtech/archunit/core/domain/Dependency.java
@@ -333,6 +333,9 @@ public String getDescription() {
         }
     }
 
+    /**
+     * Predefined {@link DescribedPredicate predicates} targeting {@link Dependency}.
+     */
     public static final class Predicates {
         private Predicates() {
         }
@@ -387,6 +390,9 @@ public static DescribedPredicate<Dependency> dependencyTarget(final DescribedPre
         }
     }
 
+    /**
+     * Predefined {@link ChainableFunction functions} to transform {@link Dependency}.
+     */
     public static final class Functions {
         private Functions() {
         }

diff --git a/archunit/src/main/java/com/tngtech/archunit/core/domain/JavaAccess.java b/archunit/src/main/java/com/tngtech/archunit/core/domain/JavaAccess.java
@@ -125,6 +125,14 @@ public Set<TryCatchBlock> getContainingTryBlocks() {
                 .collect(toImmutableSet());
     }
 
+    /**
+     * Predefined {@link DescribedPredicate predicates} targeting {@link JavaAccess}.
+     * Note that due to inheritance further predicates for {@link JavaAccess} can be found in the following locations:
+     * <ul>
+     *     <li>{@link HasName.Predicates}</li>
+     *     <li>{@link HasOwner.Predicates}</li>
+     * </ul>
+     */
     public static final class Predicates {
         private Predicates() {
         }
@@ -180,6 +188,15 @@ public boolean test(ACCESS input) {
         }
     }
 
+    /**
+     * Predefined {@link ChainableFunction functions} to transform {@link JavaAccess}.
+     * Note that due to inheritance further functions for {@link JavaAccess} can be found in the following locations:
+     * <ul>
+     *     <li>{@link HasName.Functions}</li>
+     *     <li>{@link HasName.AndFullName.Functions}</li>
+     *     <li>{@link HasOwner.Functions}</li>
+     * </ul>
+     */
     @PublicAPI(usage = ACCESS)
     public static final class Functions {
         private Functions() {

diff --git a/archunit/src/main/java/com/tngtech/archunit/core/domain/JavaCall.java b/archunit/src/main/java/com/tngtech/archunit/core/domain/JavaCall.java
@@ -28,6 +28,10 @@ public abstract class JavaCall<T extends CodeUnitCallTarget> extends JavaCodeUni
         super(builder);
     }
 
+    /**
+     * Predefined {@link DescribedPredicate predicates} targeting {@link JavaCall}.
+     * Further predicates to be used with {@link JavaCall} can be found at {@link JavaCodeUnitAccess.Predicates}.
+     */
     public static final class Predicates {
         private Predicates() {
         }

diff --git a/archunit/src/main/java/com/tngtech/archunit/core/domain/JavaClass.java b/archunit/src/main/java/com/tngtech/archunit/core/domain/JavaClass.java
@@ -1748,6 +1748,15 @@ public void markDependenciesComplete() {
         }
     }
 
+    /**
+     * Predefined {@link ChainableFunction functions} to transform {@link JavaClass}.
+     * Note that due to inheritance further functions for {@link JavaClass} can be found in the following locations:
+     * <ul>
+     *     <li>{@link HasName.Functions}</li>
+     *     <li>{@link HasName.AndFullName.Functions}</li>
+     *     <li>{@link JavaType.Functions}</li>
+     * </ul>
+     */
     public static final class Functions {
         private Functions() {
         }
@@ -2035,6 +2044,16 @@ public Set<Dependency> apply(JavaClass input) {
                 };
     }
 
+    /**
+     * Predefined {@link DescribedPredicate predicates} targeting {@link JavaClass}.
+     * Note that due to inheritance further predicates for {@link JavaClass} can be found in the following locations:
+     * <ul>
+     *     <li>{@link HasName.Predicates}</li>
+     *     <li>{@link HasName.AndFullName.Predicates}</li>
+     *     <li>{@link HasModifiers.Predicates}</li>
+     *     <li>{@link CanBeAnnotated.Predicates}</li>
+     * </ul>
+     */
     public static final class Predicates {
         private Predicates() {
         }

diff --git a/archunit/src/main/java/com/tngtech/archunit/core/domain/JavaCodeUnit.java b/archunit/src/main/java/com/tngtech/archunit/core/domain/JavaCodeUnit.java
@@ -29,6 +29,8 @@
 import com.tngtech.archunit.base.ForwardingList;
 import com.tngtech.archunit.base.MayResolveTypesViaReflection;
 import com.tngtech.archunit.base.ResolvesTypesViaReflection;
+import com.tngtech.archunit.core.domain.properties.HasName;
+import com.tngtech.archunit.core.domain.properties.HasOwner;
 import com.tngtech.archunit.core.domain.properties.HasParameterTypes;
 import com.tngtech.archunit.core.domain.properties.HasReturnType;
 import com.tngtech.archunit.core.domain.properties.HasThrowsClause;
@@ -356,6 +358,16 @@ JavaType get() {
         }
     }
 
+    /**
+     * Predefined {@link DescribedPredicate predicates} targeting {@link JavaCodeUnit}.
+     * Note that due to inheritance further predicates for {@link JavaCodeUnit} can be found in the following locations:
+     * <ul>
+     *     <li>{@link JavaMember.Predicates}</li>
+     *     <li>{@link HasParameterTypes.Predicates}</li>
+     *     <li>{@link HasReturnType.Predicates}</li>
+     *     <li>{@link HasThrowsClause.Predicates}</li>
+     * </ul>
+     */
     public static final class Predicates {
         private Predicates() {
         }
@@ -381,6 +393,16 @@ public boolean test(JavaCodeUnit input) {
         }
     }
 
+    /**
+     * Predefined {@link ChainableFunction functions} to transform {@link JavaCodeUnit}.
+     * Note that due to inheritance further functions for {@link JavaCodeUnit} can be found in the following locations:
+     * <ul>
+     *     <li>{@link HasName.Functions}</li>
+     *     <li>{@link HasName.AndFullName.Functions}</li>
+     *     <li>{@link HasReturnType.Functions}</li>
+     *     <li>{@link HasOwner.Functions}</li>
+     * </ul>
+     */
     @PublicAPI(usage = ACCESS)
     public static final class Functions {
         private Functions() {

diff --git a/archunit/src/main/java/com/tngtech/archunit/core/domain/JavaCodeUnitAccess.java b/archunit/src/main/java/com/tngtech/archunit/core/domain/JavaCodeUnitAccess.java
@@ -28,6 +28,10 @@ public abstract class JavaCodeUnitAccess<T extends CodeUnitAccessTarget> extends
         super(builder);
     }
 
+    /**
+     * Predefined {@link DescribedPredicate predicates} targeting {@link JavaCodeUnitAccess}.
+     * Further predicates to be used with {@link JavaCodeUnitAccess} can be found at {@link JavaAccess.Predicates}.
+     */
     public static final class Predicates {
         private Predicates() {
         }

diff --git a/archunit/src/main/java/com/tngtech/archunit/core/domain/JavaCodeUnitReference.java b/archunit/src/main/java/com/tngtech/archunit/core/domain/JavaCodeUnitReference.java
@@ -28,6 +28,10 @@ public abstract class JavaCodeUnitReference<T extends CodeUnitReferenceTarget> e
         super(builder);
     }
 
+    /**
+     * Predefined {@link DescribedPredicate predicates} targeting {@link JavaCodeUnitReference}.
+     * Further predicates to be used with {@link JavaCodeUnitReference} can be found at {@link JavaCodeUnitAccess.Predicates}.
+     */
     public static final class Predicates {
         private Predicates() {
         }

diff --git a/archunit/src/main/java/com/tngtech/archunit/core/domain/JavaFieldAccess.java b/archunit/src/main/java/com/tngtech/archunit/core/domain/JavaFieldAccess.java
@@ -81,6 +81,10 @@ public static AccessType forOpCode(int opCode) {
         }
     }
 
+    /**
+     * Predefined {@link DescribedPredicate predicates} targeting {@link JavaFieldAccess}.
+     * Further predicates to be used with {@link JavaFieldAccess} can be found at {@link JavaAccess.Predicates}.
+     */
     public static final class Predicates {
         private Predicates() {
         }

diff --git a/archunit/src/main/java/com/tngtech/archunit/core/domain/JavaMember.java b/archunit/src/main/java/com/tngtech/archunit/core/domain/JavaMember.java
@@ -197,6 +197,17 @@ public String toString() {
         return getClass().getSimpleName() + '{' + getFullName() + '}';
     }
 
+    /**
+     * Predefined {@link DescribedPredicate predicates} targeting {@link JavaMember}.
+     * Note that due to inheritance further predicates for {@link JavaMember} can be found in the following locations:
+     * <ul>
+     *     <li>{@link HasName.Predicates}</li>
+     *     <li>{@link HasName.AndFullName.Predicates}</li>
+     *     <li>{@link HasModifiers.Predicates}</li>
+     *     <li>{@link CanBeAnnotated.Predicates}</li>
+     *     <li>{@link HasOwner.Predicates}</li>
+     * </ul>
+     */
     public static final class Predicates {
         private Predicates() {
         }

diff --git a/archunit/src/main/java/com/tngtech/archunit/core/domain/JavaPackage.java b/archunit/src/main/java/com/tngtech/archunit/core/domain/JavaPackage.java
@@ -576,6 +576,9 @@ public interface PackageVisitor {
         void visit(JavaPackage javaPackage);
     }
 
+    /**
+     * Predefined {@link ChainableFunction functions} to transform {@link JavaPackage}.
+     */
     public static final class Functions {
         private Functions() {
         }

diff --git a/archunit/src/main/java/com/tngtech/archunit/core/domain/JavaType.java b/archunit/src/main/java/com/tngtech/archunit/core/domain/JavaType.java
@@ -39,6 +39,9 @@ public interface JavaType extends HasName {
     @PublicAPI(usage = ACCESS)
     JavaClass toErasure();
 
+    /**
+     * Predefined {@link ChainableFunction functions} to transform {@link JavaType}.
+     */
     final class Functions {
         private Functions() {
         }

diff --git a/archunit/src/main/java/com/tngtech/archunit/core/domain/ReferencedClassObject.java b/archunit/src/main/java/com/tngtech/archunit/core/domain/ReferencedClassObject.java
@@ -86,6 +86,9 @@ static ReferencedClassObject from(JavaCodeUnit owner, JavaClass javaClass, int l
         return new ReferencedClassObject(owner, javaClass, lineNumber);
     }
 
+    /**
+     * Predefined {@link ChainableFunction functions} to transform {@link ReferencedClassObject}.
+     */
     @PublicAPI(usage = ACCESS)
     public static final class Functions {
         private Functions() {

diff --git a/archunit/src/main/java/com/tngtech/archunit/core/domain/ThrowsClause.java b/archunit/src/main/java/com/tngtech/archunit/core/domain/ThrowsClause.java
@@ -134,6 +134,9 @@ protected List<ThrowsDeclaration<LOCATION>> delegate() {
         return throwsDeclarations;
     }
 
+    /**
+     * Predefined {@link ChainableFunction functions} to transform {@link ThrowsClause}.
+     */
     public static final class Functions {
         private Functions() {
         }