Document head, tail, init, last in TreeList

Common/src/main/java/at/petrak/hexcasting/api/utils/TreeList.java

@@ -464,26 +464,58 @@ protected TreeList<A> appendedAll0(Iterable<A> suffix, int k) {
         } else return new TreeListBuilder<A>().initFrom(this).addAll(suffix).result();
     }
 
+    /**
+     * @param n the number of elements to keep
+     * @return a new TreeList containing only the first {@code n} elements of this TreeList
+     */
     public final TreeList<A> take(int n) {
         return this.slice(0, n);
     }
 
+    /**
+     * @param n the number of elements to discard
+     * @return a new TreeList containing all but the first {@code n} elements of this TreeList
+     */
     public final TreeList<A> drop(int n) {
         return this.slice(n, this.length());
     }
 
+    /**
+     * @param n the number of elements to keep
+     * @return a new TreeList containing only the last {@code n} elements of this TreeList
+     */
     public final TreeList<A> takeRight(int n) {
         return this.slice(this.length() - Math.max(n, 0), this.length());
     }
 
+    /**
+     * @param n the number of elements to discard
+     * @return a new TreeList containing all but the last {@code n} elements of this TreeList
+     */
     public final TreeList<A> dropRight(int n) {
         return this.slice(0, this.length() - Math.max(n, 0));
     }
 
+    /**
+     * {@snippet :
+     *     TreeList<String> x = TreeList.from(List.of("a", "b", "c"));
+     *     assert TreeList.from(List.of("b", "c")).equals(x.tail());
+     * }
+     *
+     * @return a new TreeList containing all the elements from this TreeList except for the first one
+     */
     public TreeList<A> tail() {
         return this.slice(1, this.length());
     }
 
+    /**
+     * {@snippet :
+     *     TreeList<String> x = TreeList.from(List.of("a", "b", "c"));
+     *     assert TreeList.from(List.of("a", "b")).equals(x.init());
+     * }
+     *
+     * @return a new TreeList containing all the elements from this TreeList except for the last one
+     */
     public TreeList<A> init() {
         return this.slice(0, this.length() - 1);
     }
@@ -498,11 +530,27 @@ public TreeList<A> init() {
     /** Length of all slices up to and including index */
     abstract int treeListSlicePrefixLength(int idx);
 
+    /**
+     * {@snippet :
+     *     TreeList<String> x = TreeList.from(List.of("a", "b", "c"));
+     *     assert "a".equals(x.head());
+     * }
+     *
+     * @return the first element of this TreeList
+     */
     public final A head() {
         if(this.prefix1.length == 0) throw new NoSuchElementException("empty.head");
         else return (A) this.prefix1[0];
     }
 
+    /**
+     * {@snippet :
+     *     TreeList<String> x = TreeList.from(List.of("a", "b", "c"));
+     *     assert "c".equals(x.last());
+     * }
+     *
+     * @return the last element of this TreeList
+     */
     public A last() {
         return (A) this.prefix1[this.prefix1.length - 1];
     }