Describe the river placement, routing and grotto pool enums for the schema

core/src/main/java/art/arcane/iris/engine/object/IrisGrottoPoolLevel.java

@@ -1,5 +1,9 @@
 package art.arcane.iris.engine.object;
 
+import art.arcane.iris.engine.object.annotations.Desc;
+
+@Desc("Where the pool at the bottom of a coastal grotto sits.")
 public enum IrisGrottoPoolLevel {
+    @Desc("The pool surface sits at the dimension fluid height, so the grotto meets the sea.")
     SEA_LEVEL
 }

core/src/main/java/art/arcane/iris/engine/object/IrisRiverPlacementMode.java

@@ -1,9 +1,17 @@
 package art.arcane.iris.engine.object;
 
+import art.arcane.iris.engine.object.annotations.Desc;
+
+@Desc("Controls whether river sources may start inside a dimension, region or biome, and how strongly they are drawn there.")
 public enum IrisRiverPlacementMode {
+    @Desc("No river source may start here. Rivers may still pass through when routing allows it.")
     DISABLED,
+    @Desc("Rivers may pass through, but no source starts here.")
     TRANSIT_ONLY,
+    @Desc("Sources start here on their own merits, ranked like everywhere else.")
     NATURAL,
+    @Desc("Eligible source sites here rank ahead of sites elsewhere in the tile.")
     PREFERRED_HEADWATER,
+    @Desc("At least one source starts here whenever a site can reach a legal outlet; sources.minimumPerTile can raise that quota.")
     REQUIRED_HEADWATER
 }

core/src/main/java/art/arcane/iris/engine/object/IrisRiverRoutingMode.java

@@ -1,8 +1,15 @@
 package art.arcane.iris.engine.object;
 
+import art.arcane.iris.engine.object.annotations.Desc;
+
+@Desc("Controls whether river routes may pass through a dimension, region or biome, and at what cost.")
 public enum IrisRiverRoutingMode {
+    @Desc("Rivers never route through here.")
     BLOCK,
+    @Desc("Rivers route through here only when no cheaper path exists; transit carries a strong cost.")
     AVOID,
+    @Desc("Rivers route through here at the normal cost.")
     ALLOW,
+    @Desc("Rivers route through here at a reduced cost, so routes are drawn toward this area.")
     PREFER
 }

core/src/test/java/art/arcane/iris/core/project/IrisRiverSchemaTest.java

@@ -248,8 +248,17 @@ public class IrisRiverSchemaTest {
 
     private static List<String> enumValues(JSONObject definitions, JSONObject reference) {
         String key = reference.getString("$ref").substring("#/definitions/".length());
-        JSONArray values = definitions.getJSONObject(key).getJSONArray("enum");
+        JSONObject definition = definitions.getJSONObject(key);
-        List<String> names = new ArrayList<>(values.length());
+        List<String> names = new ArrayList<>();
+        if (definition.has("oneOf")) {
+            // A described enum lists one {const, description} entry per value.
+            JSONArray options = definition.getJSONArray("oneOf");
+            for (int index = 0; index < options.length(); index++) {
+                names.add(options.getJSONObject(index).getString("const"));
+            }
+            return names;
+        }
+        JSONArray values = definition.getJSONArray("enum");
         for (int index = 0; index < values.length(); index++) {
             names.add(values.getString(index));
         }

core/src/test/java/art/arcane/iris/engine/object/HydrologyEnumDescriptionsTest.java

@@ -0,0 +1,40 @@
+package art.arcane.iris.engine.object;
+
+import art.arcane.iris.engine.object.annotations.Desc;
+import org.junit.Test;
+
+import java.lang.reflect.Field;
+import java.util.List;
+
+import static org.junit.Assert.assertFalse;
+import static org.junit.Assert.assertNotNull;
+
+public class HydrologyEnumDescriptionsTest {
+    private static final List<Class<? extends Enum<?>>> HYDROLOGY_ENUMS = List.of(
+            IrisRiverPlacementMode.class,
+            IrisRiverRoutingMode.class,
+            IrisGrottoPoolLevel.class
+    );
+
+    @Test
+    public void hydrologyEnumsDescribeThemselvesForTheSchema() {
+        for (Class<? extends Enum<?>> type : HYDROLOGY_ENUMS) {
+            Desc description = type.getAnnotation(Desc.class);
+            assertNotNull(type.getSimpleName() + " needs a @Desc", description);
+            assertFalse(type.getSimpleName() + " has a blank @Desc", description.value().isBlank());
+        }
+    }
+
+    @Test
+    public void everyHydrologyEnumConstantDescribesItselfForTheSchema() throws NoSuchFieldException {
+        for (Class<? extends Enum<?>> type : HYDROLOGY_ENUMS) {
+            for (Enum<?> constant : type.getEnumConstants()) {
+                Field field = type.getField(constant.name());
+                Desc description = field.getAnnotation(Desc.class);
+                String label = type.getSimpleName() + "." + constant.name();
+                assertNotNull(label + " needs a @Desc", description);
+                assertFalse(label + " has a blank @Desc", description.value().isBlank());
+            }
+        }
+    }
+}