ESQL: Move description of commands in docs (#110714)

nik9000 · albertzaharovits · commit f33e549917db · 2024-07-16T11:28:55.000+03:00
This copies the first line of the description of each command to just
under the syntax so that it's "in order", before the `Parameters`
section. That way if you are reading from top to bottom you see:
```
syntax
short description
parameter names and descriptions
long description
examples
```

I've also removed the `Description` section entirely if the description
was just one sentence. So in some cases that just isn't `long
description`.
diff --git a/docs/reference/esql/processing-commands/dissect.asciidoc b/docs/reference/esql/processing-commands/dissect.asciidoc
@@ -2,6 +2,9 @@
 [[esql-dissect]]
 === `DISSECT`
 
+`DISSECT` enables you to <<esql-process-data-with-dissect-and-grok,extract
+structured data out of a string>>.
+
 **Syntax**
 
 [source,esql]
@@ -56,4 +59,4 @@ include::{esql-specs}/docs.csv-spec[tag=dissectWithToDatetime]
 include::{esql-specs}/docs.csv-spec[tag=dissectWithToDatetime-result]
 |===
 
-// end::examples[]
+// end::examples[]
diff --git a/docs/reference/esql/processing-commands/drop.asciidoc b/docs/reference/esql/processing-commands/drop.asciidoc
@@ -2,6 +2,8 @@
 [[esql-drop]]
 === `DROP`
 
+The `DROP` processing command removes one or more columns.
+
 **Syntax**
 
 [source,esql]
@@ -14,10 +16,6 @@ DROP columns
 `columns`::
 A comma-separated list of columns to remove. Supports wildcards.
 
-*Description*
-
-The `DROP` processing command removes one or more columns.
-
 *Examples*
 
 [source,esql]
diff --git a/docs/reference/esql/processing-commands/enrich.asciidoc b/docs/reference/esql/processing-commands/enrich.asciidoc
@@ -2,6 +2,9 @@
 [[esql-enrich]]
 === `ENRICH`
 
+`ENRICH` enables you to add data from existing indices as new columns using an
+enrich policy.
+
 **Syntax**
 
 [source,esql]
diff --git a/docs/reference/esql/processing-commands/eval.asciidoc b/docs/reference/esql/processing-commands/eval.asciidoc
@@ -2,6 +2,9 @@
 [[esql-eval]]
 === `EVAL`
 
+The `EVAL` processing command enables you to append new columns with calculated
+values.
+
 **Syntax**
 
 [source,esql]
diff --git a/docs/reference/esql/processing-commands/grok.asciidoc b/docs/reference/esql/processing-commands/grok.asciidoc
@@ -2,6 +2,9 @@
 [[esql-grok]]
 === `GROK`
 
+`GROK` enables you to <<esql-process-data-with-dissect-and-grok,extract
+structured data out of a string>>.
+
 **Syntax**
 
 [source,esql]
diff --git a/docs/reference/esql/processing-commands/keep.asciidoc b/docs/reference/esql/processing-commands/keep.asciidoc
@@ -2,6 +2,9 @@
 [[esql-keep]]
 === `KEEP`
 
+The `KEEP` processing command enables you to specify what columns are returned
+and the order in which they are returned.
+
 **Syntax**
 
 [source,esql]
@@ -70,7 +73,7 @@ include::{esql-specs}/docs.csv-spec[tag=keepDoubleWildcard]
 include::{esql-specs}/docs.csv-spec[tag=keep-double-wildcard-result]
 |===
 
-The following examples show how precedence rules work when a field name matches multiple expressions.   
+The following examples show how precedence rules work when a field name matches multiple expressions.
 
 Complete field name has precedence over wildcard expressions:
 
diff --git a/docs/reference/esql/processing-commands/limit.asciidoc b/docs/reference/esql/processing-commands/limit.asciidoc
@@ -2,6 +2,9 @@
 [[esql-limit]]
 === `LIMIT`
 
+The `LIMIT` processing command enables you to limit the number of rows that are
+returned.
+
 **Syntax**
 
 [source,esql]
diff --git a/docs/reference/esql/processing-commands/lookup.asciidoc b/docs/reference/esql/processing-commands/lookup.asciidoc
@@ -4,6 +4,9 @@
 
 experimental::["LOOKUP is a highly experimental and only available in SNAPSHOT versions."]
 
+`LOOKUP` matches values from the input against a `table` provided in the request,
+adding the other fields from the `table` to the output.
+
 **Syntax**
 
 [source,esql]
@@ -19,11 +22,6 @@ The name of the `table` provided in the request to match.
 `match_field`::
 The fields in the input to match against the table.
 
-*Description*
-
-`LOOKUP` matches values from the input against a `table` provided in the request,
-adding the other fields from the `table` to the output.
-
 *Examples*
 
 // tag::examples[]
diff --git a/docs/reference/esql/processing-commands/mv_expand.asciidoc b/docs/reference/esql/processing-commands/mv_expand.asciidoc
@@ -4,6 +4,9 @@
 
 preview::[]
 
+The `MV_EXPAND` processing command expands multivalued columns into one row per
+value, duplicating other columns.
+
 **Syntax**
 
 [source,esql]
@@ -16,11 +19,6 @@ MV_EXPAND column
 `column`::
 The multivalued column to expand.
 
-*Description*
-
-The `MV_EXPAND` processing command expands multivalued columns into one row per
-value, duplicating other columns.
-
 *Example*
 
 [source.merge.styled,esql]
diff --git a/docs/reference/esql/processing-commands/rename.asciidoc b/docs/reference/esql/processing-commands/rename.asciidoc
@@ -2,6 +2,8 @@
 [[esql-rename]]
 === `RENAME`
 
+The `RENAME` processing command renames one or more columns.
+
 **Syntax**
 
 [source,esql]
diff --git a/docs/reference/esql/processing-commands/sort.asciidoc b/docs/reference/esql/processing-commands/sort.asciidoc
@@ -2,6 +2,8 @@
 [[esql-sort]]
 === `SORT`
 
+The `SORT` processing command sorts a table on one or more columns.
+
 **Syntax**
 
 [source,esql]
diff --git a/docs/reference/esql/processing-commands/stats.asciidoc b/docs/reference/esql/processing-commands/stats.asciidoc
@@ -2,6 +2,9 @@
 [[esql-stats-by]]
 === `STATS ... BY`
 
+The `STATS ... BY` processing command groups rows according to a common value
+and calculate one or more aggregated values over the grouped rows.
+
 **Syntax**
 
 [source,esql]
diff --git a/docs/reference/esql/processing-commands/where.asciidoc b/docs/reference/esql/processing-commands/where.asciidoc
@@ -2,6 +2,9 @@
 [[esql-where]]
 === `WHERE`
 
+The `WHERE` processing command produces a table that contains all the rows from
+the input table for which the provided condition evaluates to `true`.
+
 **Syntax**
 
 [source,esql]
@@ -14,11 +17,6 @@ WHERE expression
 `expression`::
 A boolean expression.
 
-*Description*
-
-The `WHERE` processing command produces a table that contains all the rows from
-the input table for which the provided condition evaluates to `true`.
-
 *Examples*
 
 [source,esql]
@@ -33,7 +31,7 @@ Which, if `still_hired` is a boolean field, can be simplified to:
 include::{esql-specs}/docs.csv-spec[tag=whereBoolean]
 ----
 
-Use date math to retrieve data from a specific time range. For example, to 
+Use date math to retrieve data from a specific time range. For example, to
 retrieve the last hour of logs:
 
 [source,esql]
@@ -59,4 +57,4 @@ include::../functions/rlike.asciidoc[tag=body]
 
 include::../functions/in.asciidoc[tag=body]
 
-For a complete list of all operators, refer to <<esql-operators>>.
+For a complete list of all operators, refer to <<esql-operators>>.
diff --git a/docs/reference/esql/source-commands/from.asciidoc b/docs/reference/esql/source-commands/from.asciidoc
@@ -2,6 +2,9 @@
 [[esql-from]]
 === `FROM`
 
+The `FROM` source command returns a table with data from a data stream, index,
+or alias.
+
 **Syntax**
 
 [source,esql]
diff --git a/docs/reference/esql/source-commands/row.asciidoc b/docs/reference/esql/source-commands/row.asciidoc
@@ -2,6 +2,9 @@
 [[esql-row]]
 === `ROW`
 
+The `ROW` source command produces a row with one or more columns with values
+that you specify. This can be useful for testing.
+
 **Syntax**
 
 [source,esql]
@@ -18,11 +21,6 @@ The column name.
 The value for the column. Can be a literal, an expression, or a
 <<esql-functions,function>>.
 
-*Description*
-
-The `ROW` source command produces a row with one or more columns with values
-that you specify. This can be useful for testing.
-
 *Examples*
 
 [source.merge.styled,esql]
diff --git a/docs/reference/esql/source-commands/show.asciidoc b/docs/reference/esql/source-commands/show.asciidoc
@@ -2,6 +2,9 @@
 [[esql-show]]
 === `SHOW`
 
+The `SHOW` source command returns information about the deployment and
+its capabilities.
+
 **Syntax**
 
 [source,esql]
@@ -14,15 +17,10 @@ SHOW item
 `item`::
 Can only be `INFO`.
 
-*Description*
-
-The `SHOW` source command returns information about the deployment and
-its capabilities:
-
-* Use `SHOW INFO` to return the deployment's version, build date and hash.
-
 *Examples*
 
+Use `SHOW INFO` to return the deployment's version, build date and hash.
+
 [source,esql]
 ----
 SHOW INFO
