From 1310a4bb84f601c686f2593d6495e6426e69d1ba Mon Sep 17 00:00:00 2001
From: Aly <me@s5.pm>
Date: Wed, 15 Jul 2026 22:50:42 -0600
Subject: [PATCH 1/2] document head, tail, init, last with snippets and
 take/drop(right) with return info

---
 .../petrak/hexcasting/api/utils/TreeList.java | 48 +++++++++++++++++++
 1 file changed, 48 insertions(+)

diff --git a/Common/src/main/java/at/petrak/hexcasting/api/utils/TreeList.java b/Common/src/main/java/at/petrak/hexcasting/api/utils/TreeList.java
index aed3b14424..6ccd659a12 100644
--- a/Common/src/main/java/at/petrak/hexcasting/api/utils/TreeList.java
+++ b/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];
     }

From 3f8543177c445fb7450428ca3b1f1018988809fc Mon Sep 17 00:00:00 2001
From: Aly <me@s5.pm>
Date: Thu, 16 Jul 2026 22:36:08 -0600
Subject: [PATCH 2/2] remove snippets

---
 .../petrak/hexcasting/api/utils/TreeList.java | 20 -------------------
 1 file changed, 20 deletions(-)

diff --git a/Common/src/main/java/at/petrak/hexcasting/api/utils/TreeList.java b/Common/src/main/java/at/petrak/hexcasting/api/utils/TreeList.java
index 6ccd659a12..074e0626dd 100644
--- a/Common/src/main/java/at/petrak/hexcasting/api/utils/TreeList.java
+++ b/Common/src/main/java/at/petrak/hexcasting/api/utils/TreeList.java
@@ -497,11 +497,6 @@ public final TreeList<A> dropRight(int n) {
     }
 
     /**
-     * {@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() {
@@ -509,11 +504,6 @@ public TreeList<A> tail() {
     }
 
     /**
-     * {@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() {
@@ -531,11 +521,6 @@ public TreeList<A> init() {
     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() {
@@ -544,11 +529,6 @@ public final A head() {
     }
 
     /**
-     * {@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() {