Require all functions to provide examples (#135094)

docs/reference/query-languages/esql/_snippets/functions/examples/copy_sign.md

@@ -0,0 +1,16 @@
+% This is generated by ESQL's AbstractFunctionTestCase. Do not edit it. See ../README.md for how to regenerate it.
+
+**Example**
+
+```esql
+FROM employees
+| EVAL cs1 = COPY_SIGN(salary, LEAST(salary_change))
+```
+
+| emp_no:integer | salary:integer | salary_change:double | cs1:integer |
+| --- | --- | --- | --- |
+| 10001 | 57305 | 1.19 | 57305 |
+| 10002 | 56371 | [-7.23, 11.17] | -56371 |
+| 10003 | 61805 | [12.82, 14.68] | 61805 |
+
+

docs/reference/query-languages/esql/_snippets/functions/layout/copy_sign.md

@@ -21,3 +21,6 @@ stack: ga 9.1.0
 
 :::{include} ../types/copy_sign.md
 :::
+
+:::{include} ../examples/copy_sign.md
+:::

docs/reference/query-languages/esql/kibana/definition/functions/copy_sign.json

@@ -167,6 +167,9 @@
       "returnType" : "long"
     }
   ],
+  "examples" : [
+    "FROM employees\n| EVAL cs1 = COPY_SIGN(salary, LEAST(salary_change))"
+  ],
   "preview" : false,
   "snapshot_only" : false
 }

docs/reference/query-languages/esql/kibana/docs/functions/copy_sign.md

@@ -4,3 +4,8 @@
 Returns a value with the magnitude of the first argument and the sign of the second argument.
 This function is similar to Java's Math.copySign(double magnitude, double sign) which is
 similar to `copysign` from [IEEE 754](https://en.wikipedia.org/wiki/IEEE_754).
+
+```esql
+FROM employees
+| EVAL cs1 = COPY_SIGN(salary, LEAST(salary_change))
+```

x-pack/plugin/esql/qa/testFixtures/src/main/resources/math.csv-spec

@@ -1855,15 +1855,19 @@ cs1:double | cs2:integer | cs3:integer
 copySignWithMixedNumericValuesWithMV
 required_capability: copy_sign
 
+// tag::copy_sign[]
 FROM employees
 | EVAL cs1 = COPY_SIGN(salary, LEAST(salary_change))
+// end::copy_sign[]
 | KEEP emp_no, salary, salary_change, cs1
 | SORT emp_no
 | LIMIT 3
 ;
 
-    emp_no:integer | salary:integer | salary_change:double | cs1:integer
-    10001          | 57305          | 1.19                 | 57305
-    10002          | 56371          | [-7.23, 11.17]       | -56371  
-    10003          | 61805          | [12.82, 14.68]       | 61805  
+// tag::copy_sign-result[]
+emp_no:integer | salary:integer | salary_change:double | cs1:integer
+10001          | 57305          | 1.19                 | 57305
+10002          | 56371          | [-7.23, 11.17]       | -56371
+10003          | 61805          | [12.82, 14.68]       | 61805
+// end::copy_sign-result[]
 ;

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

@@ -19,6 +19,7 @@ import org.elasticsearch.xpack.esql.core.expression.TypeResolutions;
 import org.elasticsearch.xpack.esql.core.tree.NodeInfo;
 import org.elasticsearch.xpack.esql.core.tree.Source;
 import org.elasticsearch.xpack.esql.core.type.DataType;
+import org.elasticsearch.xpack.esql.expression.function.Example;
 import org.elasticsearch.xpack.esql.expression.function.FunctionAppliesTo;
 import org.elasticsearch.xpack.esql.expression.function.FunctionAppliesToLifecycle;
 import org.elasticsearch.xpack.esql.expression.function.FunctionInfo;
@@ -69,7 +70,8 @@ public class CopySign extends EsqlScalarFunction {
             This function is similar to Java's Math.copySign(double magnitude, double sign) which is
             similar to `copysign` from [IEEE 754](https://en.wikipedia.org/wiki/IEEE_754).""",
         returnType = { "double", "integer", "long" },
-        appliesTo = { @FunctionAppliesTo(lifeCycle = FunctionAppliesToLifecycle.GA, version = "9.1.0") }
+        appliesTo = { @FunctionAppliesTo(lifeCycle = FunctionAppliesToLifecycle.GA, version = "9.1.0") },
+        examples = { @Example(file = "math", tag = "copy_sign") }
     )
     public CopySign(
         Source source,

x-pack/plugin/esql/src/test/java/org/elasticsearch/xpack/esql/expression/function/DocsV3Support.java

@@ -1402,6 +1402,11 @@ public abstract class DocsV3Support {
                     builder.value(loadExample(example.file(), example.tag()));
                 }
                 builder.endArray();
+            } else if (info.operator().isEmpty()) {
+                // CI will fail in Kibana if we add a function with no examples
+                throw new IllegalArgumentException(
+                    "Failed to write Kibana function definition: no examples found for function [" + name + "]."
+                );
             }
             builder.field("preview", info.preview());
             builder.field("snapshot_only", EsqlFunctionRegistry.isSnapshotOnly(name));