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

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,32 @@
 [[indices-flush]]
-=== Flush
+=== Flush API
+++++
+<titleabbrev>Flush</titleabbrev>
+++++
+
+Flushes one or more indices.
+
+[source,console]
+--------------------------------------------------
+POST /twitter/_flush
+--------------------------------------------------
+// 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}
 
 Flushing an index is the process of making sure that any data that is currently
 only stored in the <<index-modules-translog,transaction log>> is also
@@ -22,49 +49,90 @@ call the flush API after indexing some documents then a successful response
 indicates that {es} has flushed all the documents that were indexed before the
 flush API was called.
 
-[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 flush operation will block until the
-flush can be executed if another flush operation is already executing. If set to
-`false` then an exception will be thrown on the shard level if another flush
-operation is already running. Defaults to `true`.
 
-`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 can be used to force
-the generation number of the transaction log to be incremented even if no
-uncommitted changes are present. This parameter should be considered 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]
 
-The flush API can be applied to more than one index with a single call, or even
-on `_all` the indices.
+include::{docdir}/rest-api/common-parms.asciidoc[tag=expand-wildcards]
++
+Defaults to `open`.
 
-[source,js]
---------------------------------------------------
-POST kimchy,elasticsearch/_flush
+`force`::
++
+--
+(Optional, boolean)
+If `true`,
+the request forces a flush
+even if there are no changes to commit to the index.
+Defaults to `true`.
 
-POST _flush
---------------------------------------------------
-// CONSOLE
+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,console]
+----
+POST /kimchy/_flush
+----
+// TEST[s/^/PUT kimchy\n/]
+
+
+[[flush-multi-index]]
+===== Flush several indices
+
+[source,console]
+----
+POST /kimchy,elasticsearch/_flush
+----
 // 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,console]
+----
+POST /_flush
+----

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="_repositories"]
 === Snapshot repositories

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: