Better description for SortAware

Author: luigidellaquila

x-pack/plugin/esql/src/main/java/org/elasticsearch/xpack/esql/plan/logical/SortAware.java

@@ -9,23 +9,89 @@
 
 /**
  * This interface is intended to check redundancy of a previous SORT.
+ *<p>
  *
- * Eg. if a MY_COMMAND that implements this interface is used after a sort, and if dependsOnInputOrder() = false,
+ * An example is with commands that compute values record by record, regardless of the input order
+ * and that don't rely on the context (intended as previous/next records).
+ *
+ * <hr>
+ * <p>
+ *
+ * Example 1: if a MY_COMMAND that implements this interface is used between two sorts, and if dependsOnInputOrder() = false,
  * then we can assume that
  * <p>
  * <code>
- * | SORT x | MY_COMMAND
+ * | SORT x, y, z | MY_COMMAND | SORT a, b, c
  * </code>
  * <p>
  * is equivalent to
  * <p>
  * <code>
- * | MY_COMMAND
+ * | MY_COMMAND | SORT a, b, c
  * </code>
+ *
+ * <hr>
+ * <p>
+ *
+ * Example 2: commands that make previous order irrelevant, eg. because they collapse the results;
+ * STATS is one of them, eg.
+ *
+ * <p>
+ * <code>
+ * | SORT x, y, z | STATS count(*)
+ * </code>
+ * <p>
+ * is equivalent to
+ * <p>
+ * <code>
+ * | STATS count(*)
+ * </code>
+ * <p>
+ *
+ * and if MY_COMMAND implements this interface and if dependsOnInputOrder() = false, then
+ *
+ * <p>
+ * <code>
+ * | SORT x, y, z | MY_COMMAND | STATS count(*)
+ * </code>
+ * <p>
+ * is equivalent to
+ * <p>
+ * <code>
+ * | MY_COMMAND | STATS count(*)
+ * </code>
+ *
+ * <hr>
  * <p>
  *
  * In all the other cases, eg. if the command does not implement this interface, or if dependsOnInputOrder() = true
- * then we assume that the SORT is still relevant and cannot be pruned.
+ * then we assume that the previous SORT is still relevant and cannot be pruned.
+ *
+ * <hr>
+ * <p>
+ *
+ * Eg. LIMIT does <b>not</b> implement this interface, because
+ *
+ * <p>
+ * <code>
+ * | SORT x, y, z | LIMIT 10 | SORT a, b, c
+ * </code>
+ * <p>
+ * is <b>NOT</b> equivalent to
+ * <p>
+ * <code>
+ * | LIMIT 10 | SORT a, b, c
+ * </code>
+ *
+ * <hr>
+ * <p>
+ *
+ * For n-ary plans that implement this interface,
+ * we assume that the above applies to all the children, ie.
+ * <ul>
+ *     <li>if dependsOnInputOrder() = false, sorts can be pruned on all the children</li>
+ *     <li>if dependsOnInputOrder() = true, sorts cannot be pruned on any of the children</li>
+ * </ul>
  */
 public interface SortAware {