[DOCS] Reformat flush API docs (#46875) (#47232)

Author: jrodewig

docs/reference/index-modules/allocation/delayed.asciidoc

@@ -28,7 +28,7 @@ this scenario:
 If the master had just waited for a few minutes, then the missing shards could
 have been re-allocated to Node 5 with the minimum of network traffic.  This
 process would be even quicker for idle shards (shards not receiving indexing
-requests) which have been automatically <<synced-flush-api,sync-flushed>>.
+requests) which have been automatically <<indices-synced-flush-api,sync-flushed>>.
 
 The allocation of replica shards which become unassigned because a node has
 left can be delayed with the `index.unassigned.node_left.delayed_timeout`

docs/reference/indices/flush.asciidoc

@@ -1,5 +1,33 @@
 [[indices-flush]]
-=== Flush
+=== Flush API
+++++
+<titleabbrev>Flush</titleabbrev>
+++++
+
+Flushes one or more indices.
+
+[source,js]
+--------------------------------------------------
+POST /twitter/_flush
+--------------------------------------------------
+// CONSOLE
+// TEST[setup:twitter]
+
+
+[[flush-api-request]]
+==== {api-request-title}
+
+`POST /<index>/flush`
+
+`GET /<index>/flush`
+
+`POST /flush`
+
+`GET /flush`
+
+
+[[flush-api-desc]]
+==== {api-description-title}
 
 The flush API allows to flush one or more indices through an API. The
 flush process of an index makes sure that any data that is currently only
@@ -9,47 +37,93 @@ reindexed from the transaction logs after the Lucene indexed is opened. By
 default, Elasticsearch uses heuristics in order to automatically
 trigger flushes as required. It is rare for users to need to call the API directly.
 
-[source,js]
---------------------------------------------------
-POST twitter/_flush
---------------------------------------------------
-// CONSOLE
-// TEST[setup:twitter]
 
-[float]
-[[flush-parameters]]
-==== Request Parameters
+[[flush-api-path-params]]
+==== {api-path-parms-title}
 
-The flush API accepts the following request parameters:
+include::{docdir}/rest-api/common-parms.asciidoc[tag=index]
++
+To flush all indices,
+omit this parameter
+or use a value of `_all` or `*`.
 
-[horizontal]
-`wait_if_ongoing`::  If set to `true`(the default value) the flush operation will
-block until the flush can be executed if another flush operation is already executing.
 
-`force`:: Whether a flush should be forced even if it is not necessarily needed i.e.
-if no changes will be committed to the index. This is useful if transaction log IDs
-should be incremented even if no uncommitted changes are present.
-(This setting can be considered as internal)
+[[flush-api-query-params]]
+==== {api-query-parms-title}
 
-[float]
-[[flush-multi-index]]
-==== Multi Index
+include::{docdir}/rest-api/common-parms.asciidoc[tag=allow-no-indices]
+
+include::{docdir}/rest-api/common-parms.asciidoc[tag=expand-wildcards]
++
+Defaults to `open`.
 
-The flush API can be applied to more than one index with a single call,
-or even on `_all` the indices.
+`force`::
++
+--
+(Optional, boolean)
+If `true`,
+the request forces a flush
+even if there are no changes to commit to the index.
+Defaults to `true`.
+
+You can use this parameter
+to increment the generation number of the transaction log.
+
+This parameter is considered internal.
+--
+
+
+include::{docdir}/rest-api/common-parms.asciidoc[tag=index-ignore-unavailable]
+
+`wait_if_ongoing`::
++
+--
+(Optional, boolean)
+If `true`,
+the flush operation blocks until execution
+when another flush operation is running.
+
+
+If `false`,
+{es} returns an error
+if you request a flush
+when another flush operation is running.
+
+Defaults to `true`.
+--
+
+
+[[flush-api-example]]
+==== {api-examples-title}
+
+
+[[flush-api-specific-ex]]
+===== Flush a specific index
 
 [source,js]
---------------------------------------------------
-POST kimchy,elasticsearch/_flush
+----
+POST /kimchy/_flush
+----
+// CONSOLE
+// TEST[s/^/PUT kimchy\n/]
 
-POST _flush
---------------------------------------------------
+
+[[flush-multi-index]]
+===== Flush several indices
+
+[source,js]
+----
+POST /kimchy,elasticsearch/_flush
+----
 // CONSOLE
 // TEST[s/^/PUT kimchy\nPUT elasticsearch\n/]
 
 
-[float]
-[[synced-flush-api]]
-==== Synced Flush
+[[flush-api-all-ex]]
+===== Flush all indices
 
-See <<indices-synced-flush-api>>.
+[source,js]
+----
+POST /_flush
+----
+// CONSOLE

docs/reference/redirects.asciidoc

@@ -760,7 +760,7 @@ See <<explain-analyze-api>>.
 
 [role="exclude",id="indices-synced-flush"]
 === Synced flush API
-See <<synced-flush-api>>.
+See <<indices-synced-flush-api>>.
 
 [role="exclude",id="ccs-reduction"]
 === {ccs-cap} reduction

docs/reference/upgrade/cluster_restart.asciidoc

@@ -20,7 +20,7 @@ include::disable-shard-alloc.asciidoc[]
 . *Stop indexing and perform a synced flush.*
 +
 --
-Performing a <<synced-flush-api, synced-flush>> speeds up shard
+Performing a <<indices-synced-flush-api, synced-flush>> speeds up shard
 recovery.
 
 include::synced-flush.asciidoc[]

docs/reference/upgrade/rolling_upgrade.asciidoc

@@ -29,7 +29,7 @@ include::disable-shard-alloc.asciidoc[]
 --
 While you can continue indexing during the upgrade, shard recovery
 is much faster if you temporarily stop non-essential indexing and perform a
-<<synced-flush-api, synced-flush>>.
+<<indices-synced-flush-api, synced-flush>>.
 
 include::synced-flush.asciidoc[]
 
@@ -132,7 +132,7 @@ As soon as another node is upgraded, the replicas can be assigned and the
 status will change to `green`.
 ====================================================
 
-Shards that were not <<synced-flush-api,sync-flushed>> might take longer to
+Shards that were not <<indices-synced-flush-api,sync-flushed>> might take longer to
 recover.  You can monitor the recovery status of individual shards by
 submitting a <<cat-recovery,`_cat/recovery`>> request: