From 4ec35817ae67ddc4afc6ddfe4047eff33451d43f Mon Sep 17 00:00:00 2001
From: Peter Gafert <peter.gafert@tngtech.com>
Date: Sat, 25 Jun 2022 12:47:04 +0700
Subject: [PATCH] fixup! extend Onion Architecture to allow defining components
 by predicate

Tried to improve Javadoc of `belongTo...()`

Signed-off-by: Peter Gafert <peter.gafert@tngtech.com>
---
 .../archunit/core/domain/JavaClass.java       | 30 +++++++++++++++++--
 1 file changed, 27 insertions(+), 3 deletions(-)

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
index cebb90c89a..4c9f389b68 100644
--- a/archunit/src/main/java/com/tngtech/archunit/core/domain/JavaClass.java
+++ b/archunit/src/main/java/com/tngtech/archunit/core/domain/JavaClass.java
@@ -2355,7 +2355,27 @@ public static DescribedPredicate<JavaClass> equivalentTo(final Class<?> clazz) {
 
         /**
          * A predicate to determine if a {@link JavaClass} "belongs" to one of the passed {@link Class classes},
-         * where we define "belong" as being equivalent to the class itself or any inner/anonymous class of this class.
+         * where "belong" means that this {@link JavaClass} is equivalent to
+         * <ul>
+         *     <li>any of the passed {@link Class classes}</li>
+         *     <li>any nested/inner/anonymous class of one of the passed {@link Class classes}</li>
+         * </ul>
+         *
+         * For example {@code belongToAnyOf(Outer.class)} would apply to the following cases
+         * <pre><code>
+         * class Outer {
+         *     // Inner would match belongToAnyOf(Outer.class) since it is an inner class of Outer
+         *     class Inner {}
+         *
+         *     void call() {
+         *         // this anonymous class would also match belongToAnyOf(Outer.class) since it is declared within Outer
+         *         new Serializable() {}
+         *     }
+         * }
+         *
+         * // this class would not match, since it is neither Outer itself nor nested within the class body of Outer
+         * class Other {}
+         * </code></pre>
          *
          * @param classes The {@link Class classes} to check the {@link JavaClass} and its enclosing classes against
          * @return A {@link DescribedPredicate} returning true, if and only if the tested {@link JavaClass} is equivalent to
@@ -2373,8 +2393,12 @@ public static DescribedPredicate<JavaClass> belongToAnyOf(Class<?>... classes) {
 
         /**
          * A predicate to determine if a {@link JavaClass} "belongs" to a class matching the given predicate,
-         * where we define "belong" as being equivalent to the class itself or any inner/anonymous class of this class.
-         * <br><br>
+         * where "belong" means that this {@link JavaClass} is
+         * <ul>
+         *     <li>directly matching the given predicate</li>
+         *     <li>a nested/inner/anonymous class of another {@link JavaClass} matching the predicate</li>
+         * </ul>
+         *
          * For example {@code belongTo(annotatedWith(Something.class))} would apply to the following cases
          * <pre><code>
          *{@literal @}Something