From 7aae6dc31c7e465a49a1ff1cdbacbf1fae37ec47 Mon Sep 17 00:00:00 2001
From: Glease <4586901+Glease@users.noreply.github.com>
Date: Thu, 15 Sep 2022 16:15:12 +0800
Subject: [PATCH] more documentation efforts...

---
 .../structure/IStructureElement.java          |  3 ++-
 .../structure/StructureDefinition.java        | 27 ++++++++++++++-----
 2 files changed, 22 insertions(+), 8 deletions(-)

diff --git a/src/main/java/com/gtnewhorizon/structurelib/structure/IStructureElement.java b/src/main/java/com/gtnewhorizon/structurelib/structure/IStructureElement.java
index 553ab3ee..3769b537 100644
--- a/src/main/java/com/gtnewhorizon/structurelib/structure/IStructureElement.java
+++ b/src/main/java/com/gtnewhorizon/structurelib/structure/IStructureElement.java
@@ -22,7 +22,8 @@ import net.minecraft.util.IChatComponent;
 import net.minecraft.world.World;
 
 /**
- * Use StructureUtility to instantiate
+ * Use StructureUtility to instantiate. These are the building blocks for your {@link IStructureDefinition}. It represents
+ * what a particular element can be and how this particular element should be autoplaced.
  */
 public interface IStructureElement<T> {
     boolean check(T t, World world, int x, int y, int z);
diff --git a/src/main/java/com/gtnewhorizon/structurelib/structure/StructureDefinition.java b/src/main/java/com/gtnewhorizon/structurelib/structure/StructureDefinition.java
index c82ff789..71715d13 100644
--- a/src/main/java/com/gtnewhorizon/structurelib/structure/StructureDefinition.java
+++ b/src/main/java/com/gtnewhorizon/structurelib/structure/StructureDefinition.java
@@ -53,18 +53,22 @@ public class StructureDefinition<T> implements IStructureDefinition<T> {
         }
 
         /**
-         * Adds shape
-         * + is anything but air
-         * - is air checks
-         * space bar is skip
-         * ~ is also skip (but marks controller position, optional. implementation wise it is a space...)
-         * rest needs to be defined
+         * Adds shape. Shape is a two-dimensional string array. Each <b>character</b> inside any of these strings will
+         * be later mapped to a particular type of {@link IStructureElement} as indicated by {@link #addElement(Character, IStructureElement)}.
          * <p>
          * next char is next block(a)
          * next string is next line(b)
          * next string[] is next slice(c)
          * <p>
-         * char A000-FFFF range is reserved for generated skips
+         * There are a few special reserved characters that are pre-mapped to some common structure elements
+         * <ul>
+         * <li>+ is anything but air</li>
+         * <li>- is air checks</li>
+         * <li>space bar is skip</li>
+         * <li>~ is also skip (but marks controller position, not optional)</li>
+         * <li>char {@code A000-FFFF} range is reserved for generated skips</li>
+         * </ul>
+         * <p>
          *
          * @param name           unlocalized/code name
          * @param structurePiece generated or written struct - DO NOT STORE IT ANYWHERE, or at least set them to null afterwards
@@ -149,11 +153,20 @@ public class StructureDefinition<T> implements IStructureDefinition<T> {
             return this;
         }
 
+        /**
+         * @deprecated use the unboxed version
+         */
+        @Deprecated
         public Builder<T> addElement(Character name, IStructureElement<T> structurePiece) {
             elements.putIfAbsent(name, structurePiece);
             return this;
         }
 
+        public Builder<T> addElement(char name, IStructureElement<T> structurePiece) {
+            elements.putIfAbsent(name, structurePiece);
+            return this;
+        }
+
         public IStructureDefinition<T> build() {
             Map<String, IStructureElement<T>[]> structures = compileStructureMap();
             return new StructureDefinition<>(