[ES|QL] Add/Modify annotations for operators for better doc generation (

#108220)

* annotation for operators

docs/reference/esql/functions/description/cidr_match.asciidoc

@@ -0,0 +1,5 @@
+// This is generated by ESQL's AbstractFunctionTestCase. Do no edit it. See ../README.md for how to regenerate it.
+
+*Description*
+
+Returns true if the provided IP is contained in one of the provided CIDR blocks.

docs/reference/esql/functions/description/ends_with.asciidoc

@@ -2,4 +2,4 @@
 
 *Description*
 
-Returns a boolean that indicates whether a keyword string ends with another string
+Returns a boolean that indicates whether a keyword string ends with another string.

docs/reference/esql/functions/description/starts_with.asciidoc

@@ -2,4 +2,4 @@
 
 *Description*
 
-Returns a boolean that indicates whether a keyword string starts with another string
+Returns a boolean that indicates whether a keyword string starts with another string.

docs/reference/esql/functions/examples/cidr_match.asciidoc

@@ -0,0 +1,13 @@
+// This is generated by ESQL's AbstractFunctionTestCase. Do no edit it. See ../README.md for how to regenerate it.
+
+*Example*
+
+[source.merge.styled,esql]
+----
+include::{esql-specs}/ip.csv-spec[tag=cdirMatchMultipleArgs]
+----
+[%header.monospaced.styled,format=dsv,separator=|]
+|===
+include::{esql-specs}/ip.csv-spec[tag=cdirMatchMultipleArgs-result]
+|===
+

docs/reference/esql/functions/examples/ends_with.asciidoc

@@ -0,0 +1,13 @@
+// This is generated by ESQL's AbstractFunctionTestCase. Do no edit it. See ../README.md for how to regenerate it.
+
+*Example*
+
+[source.merge.styled,esql]
+----
+include::{esql-specs}/string.csv-spec[tag=endsWith]
+----
+[%header.monospaced.styled,format=dsv,separator=|]
+|===
+include::{esql-specs}/string.csv-spec[tag=endsWith-result]
+|===
+

docs/reference/esql/functions/examples/starts_with.asciidoc

@@ -0,0 +1,13 @@
+// This is generated by ESQL's AbstractFunctionTestCase. Do no edit it. See ../README.md for how to regenerate it.
+
+*Example*
+
+[source.merge.styled,esql]
+----
+include::{esql-specs}/docs.csv-spec[tag=startsWith]
+----
+[%header.monospaced.styled,format=dsv,separator=|]
+|===
+include::{esql-specs}/docs.csv-spec[tag=startsWith-result]
+|===
+

docs/reference/esql/functions/kibana/definition/cidr_match.json

@@ -0,0 +1,47 @@
+{
+ "comment" : "This is generated by ESQL's AbstractFunctionTestCase. Do no edit it. See ../README.md for how to regenerate it.",
+ "type" : "eval",
+ "name" : "cidr_match",
+ "description" : "Returns true if the provided IP is contained in one of the provided CIDR blocks.",
+ "signatures" : [
+ {
+ "params" : [
+ {
+ "name" : "ip",
+ "type" : "ip",
+ "optional" : false,
+ "description" : "IP address of type `ip` (both IPv4 and IPv6 are supported)."
+ },
+ {
+ "name" : "blockX",
+ "type" : "keyword",
+ "optional" : false,
+ "description" : "CIDR block to test the IP against."
+ }
+ ],
+ "variadic" : true,
+ "returnType" : "boolean"
+ },
+ {
+ "params" : [
+ {
+ "name" : "ip",
+ "type" : "ip",
+ "optional" : false,
+ "description" : "IP address of type `ip` (both IPv4 and IPv6 are supported)."
+ },
+ {
+ "name" : "blockX",
+ "type" : "text",
+ "optional" : false,
+ "description" : "CIDR block to test the IP against."
+ }
+ ],
+ "variadic" : true,
+ "returnType" : "boolean"
+ }
+ ],
+ "examples" : [
+ "FROM hosts \n| WHERE CIDR_MATCH(ip1, \"127.0.0.2/32\", \"127.0.0.3/32\") \n| KEEP card, host, ip0, ip1"
+ ]
+}

docs/reference/esql/functions/kibana/definition/ends_with.json

@@ -2,21 +2,21 @@
  "comment" : "This is generated by ESQL's AbstractFunctionTestCase. Do no edit it. See ../README.md for how to regenerate it.",
  "type" : "eval",
  "name" : "ends_with",
- "description" : "Returns a boolean that indicates whether a keyword string ends with another string",
+ "description" : "Returns a boolean that indicates whether a keyword string ends with another string.",
  "signatures" : [
  {
  "params" : [
  {
  "name" : "str",
  "type" : "keyword",
  "optional" : false,
- "description" : ""
+ "description" : "String expression. If `null`, the function returns `null`."
  },
  {
  "name" : "suffix",
  "type" : "keyword",
  "optional" : false,
- "description" : ""
+ "description" : "String expression. If `null`, the function returns `null`."
  }
  ],
  "variadic" : false,
@@ -28,17 +28,20 @@
  "name" : "str",
  "type" : "text",
  "optional" : false,
- "description" : ""
+ "description" : "String expression. If `null`, the function returns `null`."
  },
  {
  "name" : "suffix",
  "type" : "text",
  "optional" : false,
- "description" : ""
+ "description" : "String expression. If `null`, the function returns `null`."
  }
  ],
  "variadic" : false,
  "returnType" : "boolean"
  }
+ ],
+ "examples" : [
+ "FROM employees\n| KEEP last_name\n| EVAL ln_E = ENDS_WITH(last_name, \"d\")"
  ]
 }

docs/reference/esql/functions/kibana/definition/starts_with.json

@@ -2,21 +2,21 @@
  "comment" : "This is generated by ESQL's AbstractFunctionTestCase. Do no edit it. See ../README.md for how to regenerate it.",
  "type" : "eval",
  "name" : "starts_with",
- "description" : "Returns a boolean that indicates whether a keyword string starts with another string",
+ "description" : "Returns a boolean that indicates whether a keyword string starts with another string.",
  "signatures" : [
  {
  "params" : [
  {
  "name" : "str",
  "type" : "keyword",
  "optional" : false,
- "description" : ""
+ "description" : "String expression. If `null`, the function returns `null`."
  },
  {
  "name" : "prefix",
  "type" : "keyword",
  "optional" : false,
- "description" : ""
+ "description" : "String expression. If `null`, the function returns `null`."
  }
  ],
  "variadic" : false,
@@ -28,17 +28,20 @@
  "name" : "str",
  "type" : "text",
  "optional" : false,
- "description" : ""
+ "description" : "String expression. If `null`, the function returns `null`."
  },
  {
  "name" : "prefix",
  "type" : "text",
  "optional" : false,
- "description" : ""
+ "description" : "String expression. If `null`, the function returns `null`."
  }
  ],
  "variadic" : false,
  "returnType" : "boolean"
  }
+ ],
+ "examples" : [
+ "FROM employees\n| KEEP last_name\n| EVAL ln_S = STARTS_WITH(last_name, \"B\")"
  ]
 }

docs/reference/esql/functions/kibana/docs/cidr_match.md

@@ -0,0 +1,12 @@
+<!--
+This is generated by ESQL's AbstractFunctionTestCase. Do no edit it. See ../README.md for how to regenerate it.
+-->
+
+### CIDR_MATCH
+Returns true if the provided IP is contained in one of the provided CIDR blocks.
+
+```
+FROM hosts 
+| WHERE CIDR_MATCH(ip1, "127.0.0.2/32", "127.0.0.3/32") 
+| KEEP card, host, ip0, ip1
+```

docs/reference/esql/functions/kibana/docs/ends_with.md

@@ -3,5 +3,10 @@ This is generated by ESQL's AbstractFunctionTestCase. Do no edit it. See ../READ
 -->
 
 ### ENDS_WITH
-Returns a boolean that indicates whether a keyword string ends with another string
+Returns a boolean that indicates whether a keyword string ends with another string.
 
+```
+FROM employees
+| KEEP last_name
+| EVAL ln_E = ENDS_WITH(last_name, "d")
+```

docs/reference/esql/functions/kibana/docs/starts_with.md

@@ -3,5 +3,10 @@ This is generated by ESQL's AbstractFunctionTestCase. Do no edit it. See ../READ
 -->
 
 ### STARTS_WITH
-Returns a boolean that indicates whether a keyword string starts with another string
+Returns a boolean that indicates whether a keyword string starts with another string.
 
+```
+FROM employees
+| KEEP last_name
+| EVAL ln_S = STARTS_WITH(last_name, "B")
+```

docs/reference/esql/functions/layout/cidr_match.asciidoc

@@ -0,0 +1,15 @@
+// This is generated by ESQL's AbstractFunctionTestCase. Do no edit it. See ../README.md for how to regenerate it.
+
+[discrete]
+[[esql-cidr_match]]
+=== `CIDR_MATCH`
+
+*Syntax*
+
+[.text-center]
+image::esql/functions/signature/cidr_match.svg[Embedded,opts=inline]
+
+include::../parameters/cidr_match.asciidoc[]
+include::../description/cidr_match.asciidoc[]
+include::../types/cidr_match.asciidoc[]
+include::../examples/cidr_match.asciidoc[]

docs/reference/esql/functions/layout/ends_with.asciidoc

@@ -12,3 +12,4 @@ image::esql/functions/signature/ends_with.svg[Embedded,opts=inline]
 include::../parameters/ends_with.asciidoc[]
 include::../description/ends_with.asciidoc[]
 include::../types/ends_with.asciidoc[]
+include::../examples/ends_with.asciidoc[]

docs/reference/esql/functions/layout/starts_with.asciidoc

@@ -12,3 +12,4 @@ image::esql/functions/signature/starts_with.svg[Embedded,opts=inline]
 include::../parameters/starts_with.asciidoc[]
 include::../description/starts_with.asciidoc[]
 include::../types/starts_with.asciidoc[]
+include::../examples/starts_with.asciidoc[]

docs/reference/esql/functions/like.asciidoc

@@ -13,6 +13,8 @@ The following wildcard characters are supported:
 * `*` matches zero or more characters.
 * `?` matches one character.
 
+include::./types/like.asciidoc[]
+
 [source.merge.styled,esql]
 ----
 include::{esql-specs}/docs.csv-spec[tag=like]
@@ -21,4 +23,4 @@ include::{esql-specs}/docs.csv-spec[tag=like]
 |===
 include::{esql-specs}/docs.csv-spec[tag=like-result]
 |===
-// end::body[]
+// end::body[]

docs/reference/esql/functions/operators.asciidoc

@@ -24,7 +24,7 @@ include::unary.asciidoc[]
 include::logical.asciidoc[]
 include::predicates.asciidoc[]
 include::cast.asciidoc[]
-include::cidr_match.asciidoc[]
+include::layout/cidr_match.asciidoc[]
 include::in.asciidoc[]
 include::like.asciidoc[]
 include::rlike.asciidoc[]

docs/reference/esql/functions/parameters/cidr_match.asciidoc

@@ -0,0 +1,9 @@
+// This is generated by ESQL's AbstractFunctionTestCase. Do no edit it. See ../README.md for how to regenerate it.
+
+*Parameters*
+
+`ip`::
+IP address of type `ip` (both IPv4 and IPv6 are supported).
+
+`blockX`::
+CIDR block to test the IP against.

docs/reference/esql/functions/parameters/ends_with.asciidoc

@@ -3,7 +3,7 @@
 *Parameters*
 
 `str`::
-
+String expression. If `null`, the function returns `null`.
 
 `suffix`::
-
+String expression. If `null`, the function returns `null`.

docs/reference/esql/functions/parameters/starts_with.asciidoc

@@ -3,7 +3,7 @@
 *Parameters*
 
 `str`::
-
+String expression. If `null`, the function returns `null`.
 
 `prefix`::
-
+String expression. If `null`, the function returns `null`.