added comments explaining the Comparable interface

Author: schauder

spring-data-relational/src/main/java/org/springframework/data/relational/core/mapping/AggregatePath.java

@@ -32,13 +32,16 @@
 import org.springframework.data.mapping.PersistentPropertyPath;
 import org.springframework.data.mapping.PropertyHandler;
 import org.springframework.data.relational.core.sql.SqlIdentifier;
+import org.springframework.lang.NonNull;
 import org.springframework.lang.Nullable;
 import org.springframework.util.Assert;
 
 /**
  * Represents a path within an aggregate starting from the aggregate root. The path can be iterated from the leaf to its
  * root.
  *
+ * It implements {@link Comparable} so that collections of {@code AggregatePath} instances can be sorted in a consistent way.
+ *
  * @author Jens Schauder
  * @author Mark Paluch
  * @since 3.2
@@ -264,6 +267,20 @@ default Stream<AggregatePath> stream() {
 	@Nullable
 	AggregatePath subtract(@Nullable AggregatePath basePath);
 
+	/**
+	 * Compares this {@code AggregatePath} to another {@code AggregatePath} based on their dot path notation.
+	 * <p>
+	 * This is used to get {@code AggregatePath} instances sorted in a consistent way. Since this order affects generated SQL this also affects query caches and similar.
+	 *
+	 * @param other the {@code AggregatePath} to compare to. Must not be {@literal null}.
+	 * @return a negative integer, zero, or a positive integer as this object's path is less than,
+	 * equal to, or greater than the specified object's path.
+	 */
+	@Override
+	default int compareTo(@NonNull AggregatePath other) {
+		return toDotPath().compareTo(other.toDotPath());
+	}
+
 	/**
 	 * Information about a table underlying an entity.
 	 *

spring-data-relational/src/main/java/org/springframework/data/relational/core/mapping/DefaultAggregatePath.java

@@ -303,11 +303,6 @@ public String toString() {
 				+ ((isRoot()) ? "/" : path.toDotPath());
 	}
 
-	@Override
-	public int compareTo(@NonNull AggregatePath other) {
-		return toDotPath().compareTo(other.toDotPath());
-	}
-
 	private static class AggregatePathIterator implements Iterator<AggregatePath> {
 
 		private @Nullable AggregatePath current;