[DOCS] Add DATE_DIFF function

docs/reference/esql/functions/date-time-functions.asciidoc

@@ -9,6 +9,7 @@
 
 // tag::date_list[]
 * <<esql-auto_bucket>>
+* <<esql-date_diff>>
 * <<esql-date_extract>>
 * <<esql-date_format>>
 * <<esql-date_parse>>
@@ -17,6 +18,7 @@
 // end::date_list[]
 
 include::auto_bucket.asciidoc[]
+include::date_diff.asciidoc[]
 include::date_extract.asciidoc[]
 include::date_format.asciidoc[]
 include::date_parse.asciidoc[]

docs/reference/esql/functions/date_diff.asciidoc

@@ -1,10 +1,30 @@
 [discrete]
 [[esql-date_diff]]
 === `DATE_DIFF`
-Subtract the second argument from the third argument and return their difference in multiples of the unit specified in the first argument.
-If the second argument (start) is greater than the third argument (end), then negative values are returned.
 
-[cols="^,^"]
+*Syntax*
+
+[.text-center]
+image::esql/functions/signature/date_diff.svg[Embedded,opts=inline]
+
+*Parameters*
+
+`unit`::
+Time difference unit.
+
+`startTimestamp`::
+Start timestamp.
+
+`endTimestamp`::
+End timestamp.
+
+*Description*
+
+Subtracts the `startTimestamp` from the `endTimestamp` and returns the
+difference in multiples of `unit`. If `startTimestamp` is later than the
+`endTimestamp`, negative values are returned.
+
+[cols="^,^",role="styled"]
 |===
 2+h|Datetime difference units
 
@@ -26,12 +46,18 @@ s|abbreviations
 | nanosecond  | nanoseconds, ns
 |===
 
+*Supported types*
+
+include::types/date_diff.asciidoc[]
+
+*Example*
+
 [source.merge.styled,esql]
 ----
-include::{esql-specs}/docs.csv-spec[tag=dateDiff]
+include::{esql-specs}/date.csv-spec[tag=docsDateDiff]
 ----
 [%header.monospaced.styled,format=dsv,separator=|]
 |===
-include::{esql-specs}/docs.csv-spec[tag=dateDiff-result]
+include::{esql-specs}/date.csv-spec[tag=docsDateDiff-result]
 |===
 

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

@@ -409,6 +409,19 @@ dd_oo:integer
 null
 ;
 
+docsDateDiff#[skip:-8.12.99, reason:date_diff added in 8.13]
+// tag::docsDateDiff[]
+ROW date1 = TO_DATETIME("2023-12-02T11:00:00.000Z"), date2 = TO_DATETIME("2023-12-02T11:00:00.001Z")
+| EVAL dd_ms = DATE_DIFF("microseconds", date1, date2)
+// end::docsDateDiff[]
+;
+
+// tag::docsDateDiff-result[]
+date1:date          |         date2:date          |    dd_ms:integer
+2023-12-02T11:00:00.000Z | 2023-12-02T11:00:00.001Z | 1000  
+// end::docsDateDiff-result[]
+;
+
 evalDateParseWithSimpleDate
 row a = "2023-02-01" | eval b = date_parse("yyyy-MM-dd", a) | keep b;