[CALCITE-6698] Add Javadoc to PartiallyOrderedSet#getNonChildren and getNonParents to clarify their behavior

core/src/main/java/org/apache/calcite/util/PartiallyOrderedSet.java

@@ -90,6 +90,10 @@ public class PartiallyOrderedSet<E> extends AbstractSet<E> {
    * in the set.
    */
   private final Node<E> topNode;
+  /**
+   * Synthetic node to hold all nodes that have no children. It does not appear
+   * in the set.
+   */
   private final Node<E> bottomNode;
 
   /**
@@ -681,10 +685,22 @@ private void closure(Function<E, Iterable<E>> generator, E e, ImmutableList.Buil
     }
   }
 
+  /**
+   * Returns all elements in the set that are not children. These elements appear at the top of
+   * the poset, and they usually referred to as roots/maximal elements of the poset.
+   *
+   * @return a list of elements that are not children.
+   */
   public List<E> getNonChildren() {
     return strip(topNode.childList);
   }
 
+  /**
+   * Returns all elements in the set that are not parents. These elements appear at the bottom of
+   * the poset, and they usually referred to as leafs/minimal elements of the poset.
+   *
+   * @return a list of elements that are not parents.
+   */
   public List<E> getNonParents() {
     return strip(bottomNode.parentList);
   }

core/src/test/java/org/apache/calcite/util/PartiallyOrderedSetTest.java

@@ -20,6 +20,7 @@
 
 import java.util.AbstractList;
 import java.util.ArrayList;
+import java.util.Arrays;
 import java.util.Collection;
 import java.util.LinkedHashSet;
 import java.util.List;
@@ -180,6 +181,30 @@ private static boolean isBitSuperset(Integer e1, Integer e2) {
     assertEqualsList("['ab', 'abcd']", poset.getAncestors("'a'"));
   }
 
+  @Test void testGetNonParentsOnLteIntPosetReturnsMinValue() {
+    PartiallyOrderedSet<Integer> poset =
+        new PartiallyOrderedSet<>((i, j) -> i <= j, Arrays.asList(20, 30, 40));
+    assertThat(poset.getNonParents(), hasToString("[20]"));
+  }
+
+  @Test void testGetNonChildrenOnLteIntPosetReturnsMaxValue() {
+    PartiallyOrderedSet<Integer> poset =
+        new PartiallyOrderedSet<>((i, j) -> i <= j, Arrays.asList(20, 30, 40));
+    assertThat(poset.getNonChildren(), hasToString("[40]"));
+  }
+
+  @Test void testGetNonParentsOnGteIntPosetReturnsMaxValue() {
+    PartiallyOrderedSet<Integer> poset =
+        new PartiallyOrderedSet<>((i, j) -> i >= j, Arrays.asList(20, 30, 40));
+    assertThat(poset.getNonParents(), hasToString("[40]"));
+  }
+
+  @Test void testGetNonChildrenOnGteIntPosetReturnsMinValue() {
+    PartiallyOrderedSet<Integer> poset =
+        new PartiallyOrderedSet<>((i, j) -> i >= j, Arrays.asList(20, 30, 40));
+    assertThat(poset.getNonChildren(), hasToString("[20]"));
+  }
+
   @Test void testPosetTricky() {
     final PartiallyOrderedSet<String> poset =
         new PartiallyOrderedSet<>(STRING_SUBSET_ORDERING);
@@ -195,6 +220,8 @@ private static boolean isBitSuperset(Integer e1, Integer e2) {
     printValidate(poset);
     poset.add("'ab'");
     printValidate(poset);
+    assertThat(poset.getNonChildren(), hasToString("['ac', 'ab']"));
+    assertThat(poset.getNonParents(), hasToString("['a', 'b']"));
   }
 
   @Test void testPosetBits() {