ESQL: Move description of commands in docs

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`.
nik9000 · Jul 10, 2024 · 4a0c488 · 4a0c488
1 parent 688870c
commit 4a0c488
Show file tree

Hide file tree

Showing 16 changed files with 54 additions and 38 deletions.
diff --git a/docs/reference/esql/processing-commands/dissect.asciidoc b/docs/reference/esql/processing-commands/dissect.asciidoc
@@ -9,6 +9,9 @@
 DISSECT input "pattern" [APPEND_SEPARATOR="<separator>"]
 ----
 
+`DISSECT` enables you to <<esql-process-data-with-dissect-and-grok,extract
+structured data out of a string>>.
+
 *Parameters*
 
 `input`::
@@ -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
@@ -9,6 +9,9 @@
 ENRICH policy [ON match_field] [WITH [new_name1 = ]field1, [new_name2 = ]field2, ...]
 ----
 
+`ENRICH` enables you to add data from existing indices as new columns using an
+enrich policy.
+
 *Parameters*
 
 `policy`::

diff --git a/docs/reference/esql/processing-commands/eval.asciidoc b/docs/reference/esql/processing-commands/eval.asciidoc
@@ -9,6 +9,9 @@
 EVAL [column1 =] value1[, ..., [columnN =] valueN]
 ----
 
+The `EVAL` processing command enables you to append new columns with calculated
+values.
+
 *Parameters*
 
 `columnX`::

diff --git a/docs/reference/esql/processing-commands/grok.asciidoc b/docs/reference/esql/processing-commands/grok.asciidoc
@@ -9,6 +9,9 @@
 GROK input "pattern"
 ----
 
+`GROK` enables you to <<esql-process-data-with-dissect-and-grok,extract
+structured data out of a string>>.
+
 *Parameters*
 
 `input`::

diff --git a/docs/reference/esql/processing-commands/keep.asciidoc b/docs/reference/esql/processing-commands/keep.asciidoc
@@ -9,6 +9,9 @@
 KEEP columns
 ----
 
+The `KEEP` processing command enables you to specify what columns are returned
+and the order in which they are returned.
+
 *Parameters*
 
 `columns`::
@@ -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
@@ -9,6 +9,9 @@
 LIMIT max_number_of_rows
 ----
 
+The `LIMIT` processing command enables you to limit the number of rows that are
+returned.
+
 *Parameters*
 
 `max_number_of_rows`::

diff --git a/docs/reference/esql/processing-commands/lookup.asciidoc b/docs/reference/esql/processing-commands/lookup.asciidoc
@@ -11,6 +11,9 @@ experimental::["LOOKUP is a highly experimental and only available in SNAPSHOT v
 LOOKUP table ON match_field1[, match_field2, ...]
 ----
 
+`LOOKUP` matches values from the input against a `table` provided in the request,
+adding the other fields from the `table` to the output.
+
 *Parameters*
 
 `table`::
@@ -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
@@ -11,16 +11,14 @@ preview::[]
 MV_EXPAND column
 ----
 
+The `MV_EXPAND` processing command expands multivalued columns into one row per
+value, duplicating other columns.
+
 *Parameters*
 
 `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
@@ -9,6 +9,8 @@
 RENAME old_name1 AS new_name1[, ..., old_nameN AS new_nameN]
 ----
 
+The `RENAME` processing command renames one or more columns.
+
 *Parameters*
 
 `old_nameX`::

diff --git a/docs/reference/esql/processing-commands/sort.asciidoc b/docs/reference/esql/processing-commands/sort.asciidoc
@@ -9,6 +9,8 @@
 SORT column1 [ASC/DESC][NULLS FIRST/NULLS LAST][, ..., columnN [ASC/DESC][NULLS FIRST/NULLS LAST]]
 ----
 
+The `SORT` processing command sorts a table on one or more columns.
+
 *Parameters*
 
 `columnX`::

diff --git a/docs/reference/esql/processing-commands/stats.asciidoc b/docs/reference/esql/processing-commands/stats.asciidoc
@@ -6,10 +6,13 @@
 
 [source,esql]
 ----
-STATS [column1 =] expression1[, ..., [columnN =] expressionN] 
+STATS [column1 =] expression1[, ..., [columnN =] expressionN]
 [BY grouping_expression1[, ..., grouping_expressionN]]
 ----
 
+The `STATS ... BY` processing command groups rows according to a common value
+and calculate one or more aggregated values over the grouped rows.
+
 *Parameters*
 
 `columnX`::
@@ -39,8 +42,8 @@ NOTE: `STATS` without any groups is much much faster than adding a group.
 
 NOTE: Grouping on a single expression is currently much more optimized than grouping
       on many expressions. In some tests we have seen grouping on a single `keyword`
-      column to be five times faster than grouping on two `keyword` columns. Do 
-      not try to work around this by combining the two columns together with 
+      column to be five times faster than grouping on two `keyword` columns. Do
+      not try to work around this by combining the two columns together with
       something like <<esql-concat>> and then grouping - that is not going to be
       faster.
 

diff --git a/docs/reference/esql/processing-commands/where.asciidoc b/docs/reference/esql/processing-commands/where.asciidoc
@@ -9,16 +9,14 @@
 WHERE expression
 ----
 
+The `WHERE` processing command produces a table that contains all the rows from
+the input table for which the provided condition evaluates to `true`.
+
 *Parameters*
 
 `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
@@ -9,6 +9,9 @@
 FROM index_pattern [METADATA fields]
 ----
 
+The `FROM` source command returns a table with data from a data stream, index,
+or alias.
+
 *Parameters*
 
 `index_pattern`::

diff --git a/docs/reference/esql/source-commands/row.asciidoc b/docs/reference/esql/source-commands/row.asciidoc
@@ -9,6 +9,9 @@
 ROW column1 = value1[, ..., columnN = valueN]
 ----
 
+The `ROW` source command produces a row with one or more columns with values
+that you specify. This can be useful for testing.
+
 *Parameters*
 
 `columnX`::
@@ -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
@@ -9,20 +9,18 @@
 SHOW item
 ----
 
+The `SHOW` source command returns information about the deployment and
+its capabilities.
+
 *Parameters*
 
 `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