From 1072e0f0e51e8657438b2df5b9ded5a4e2a841f9 Mon Sep 17 00:00:00 2001
From: Nik Everett <nik9000@gmail.com>
Date: Thu, 4 Sep 2025 11:44:12 -0400
Subject: [PATCH] ESQL: More docs for `DataType#UNDER_CONSTRUCTION`

Adds more explanation for the `DataType#UNDER_CONSTRUCTION`.
---
 .../xpack/esql/core/type/DataType.java        | 19 +++++++++++++++----
 1 file changed, 15 insertions(+), 4 deletions(-)

diff --git a/x-pack/plugin/esql-core/src/main/java/org/elasticsearch/xpack/esql/core/type/DataType.java b/x-pack/plugin/esql-core/src/main/java/org/elasticsearch/xpack/esql/core/type/DataType.java
index 6a54a038627a7..3c36884874454 100644
--- a/x-pack/plugin/esql-core/src/main/java/org/elasticsearch/xpack/esql/core/type/DataType.java
+++ b/x-pack/plugin/esql-core/src/main/java/org/elasticsearch/xpack/esql/core/type/DataType.java
@@ -313,10 +313,21 @@ public enum DataType {
     DENSE_VECTOR(builder().esType("dense_vector").unknownSize());
 
     /**
-     * Types that are actively being built. These types are not returned
-     * from Elasticsearch if their associated {@link FeatureFlag} is disabled.
-     * They aren't included in generated documentation. And the tests don't
-     * check that sending them to a function produces a sane error message.
+     * Types that are actively being built. These types are
+     * <ul>
+     *     <li>Not returned from Elasticsearch if their associated {@link FeatureFlag} is disabled.</li>
+     *     <li>Not included in generated documentation</li>
+     *     <li>
+     *         Not tested by {@code ErrorsForCasesWithoutExamplesTestCase} subclasses.
+     *         When a function supports a type it includes a test case in its subclass
+     *         of {@code AbstractFunctionTestCase}. If a function does not support.
+     *         them like {@code TO_STRING} then the tests won't notice. See class javadoc
+     *         for instructions on adding new types, but that usually involves adding support
+     *         for that type to a handful of functions. Once you've done that you should be
+     *         able to remove your new type from UNDER_CONSTRUCTION and update a few error
+     *         messages.
+     *     </li>
+     * </ul>
      */
     public static final Map<DataType, FeatureFlag> UNDER_CONSTRUCTION = Map.ofEntries(
         Map.entry(AGGREGATE_METRIC_DOUBLE, EsqlCorePlugin.AGGREGATE_METRIC_DOUBLE_FEATURE_FLAG),