ESQL: Document MV_SLICE limitations

x-pack/plugin/esql/src/main/java/org/elasticsearch/xpack/esql/expression/function/FunctionInfo.java

@@ -29,13 +29,18 @@
     boolean preview() default false;
 
     /**
-     * The description of the function rendered in {@code META FUNCTIONS}
-     * and the docs. These should be complete sentences.
+     * The description of the function rendered in the docs and kibana's
+     * json files that drive their IDE-like experience. These should be
+     * complete sentences but can contain asciidoc syntax. It is rendered
+     * as a single paragraph.
      */
     String description() default "";
 
     /**
-     * Detailed descriptions of the function rendered in the docs.
+     * Detailed descriptions of the function rendered in the docs. This is
+     * rendered as a single paragraph following {@link #description()} in
+     * the docs and is <strong>excluded</strong> from Kibana's IDE-like
+     * experience. It can contain asciidoc syntax.
      */
     String detailedDescription() default "";
 

x-pack/plugin/esql/src/main/java/org/elasticsearch/xpack/esql/expression/function/scalar/multivalue/MvFirst.java

@@ -59,8 +59,8 @@ public class MvFirst extends AbstractMultivalueFunction {
         description = """
             Converts a multivalued expression into a single valued column containing the
             first value. This is most useful when reading from a function that emits
-            multivalued columns in a known order like <<esql-split>>.
-
+            multivalued columns in a known order like <<esql-split>>.""",
+        detailedDescription = """
             The order that <<esql-multivalued-fields, multivalued fields>> are read from
             underlying storage is not guaranteed. It is *frequently* ascending, but don't
             rely on that. If you need the minimum value use <<esql-mv_min>> instead of

x-pack/plugin/esql/src/main/java/org/elasticsearch/xpack/esql/expression/function/scalar/multivalue/MvLast.java

@@ -59,8 +59,8 @@ public class MvLast extends AbstractMultivalueFunction {
         description = """
             Converts a multivalue expression into a single valued column containing the last
             value. This is most useful when reading from a function that emits multivalued
-            columns in a known order like <<esql-split>>.
-
+            columns in a known order like <<esql-split>>.""",
+        detailedDescription = """
             The order that <<esql-multivalued-fields, multivalued fields>> are read from
             underlying storage is not guaranteed. It is *frequently* ascending, but don't
             rely on that. If you need the maximum value use <<esql-mv_max>> instead of

x-pack/plugin/esql/src/main/java/org/elasticsearch/xpack/esql/expression/function/scalar/multivalue/MvSlice.java

@@ -68,7 +68,14 @@ public class MvSlice extends EsqlScalarFunction implements OptionalArgument, Eva
             "long",
             "text",
             "version" },
-        description = "Returns a subset of the multivalued field using the start and end index values.",
+        description = """
+            Returns a subset of the multivalued field using the start and end index values.
+            This is most useful when reading from a function that emits multivalued columns
+            in a known order like <<esql-split>> or <<esql-mv_sort>>.""",
+        detailedDescription = """
+            The order that <<esql-multivalued-fields, multivalued fields>> are read from
+            underlying storage is not guaranteed. It is *frequently* ascending, but don't
+            rely on that.""",
         examples = { @Example(file = "ints", tag = "mv_slice_positive"), @Example(file = "ints", tag = "mv_slice_negative") }
     )
     public MvSlice(