[CALCITE-6698] Add Javadoc to PartiallyOrderedSet#getNonChildren and …

…getNonParents to clarify their behavior

1. Add Javadoc to clarify the results of each method and avoid potential misinterpretation of their name.
2. Add test cases with explicit tests for the aforementioned methods.

Close #4054

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() {