From dd48d45167a51bd2586131e684118782edd16730 Mon Sep 17 00:00:00 2001
From: James Rodewig <40268737+jrodewig@users.noreply.github.com>
Date: Wed, 7 Jul 2021 10:18:21 -0400
Subject: [PATCH] [DOCS] Fix allowed `refresh` args for several doc APIs
 (#74749)

We incorrectly list `wait_for` as a valid `refresh` argument for the
following APIs:

* Delete by query
* Multi get
* Reindex

This fixes that error. It also updates the get API docs for consistency.

Closes #65031
---
 docs/reference/docs/delete-by-query.asciidoc | 4 +++-
 docs/reference/docs/get.asciidoc             | 5 ++---
 docs/reference/docs/multi-get.asciidoc       | 4 +++-
 docs/reference/docs/reindex.asciidoc         | 4 +++-
 4 files changed, 11 insertions(+), 6 deletions(-)

diff --git a/docs/reference/docs/delete-by-query.asciidoc b/docs/reference/docs/delete-by-query.asciidoc
index 80de31090bb68..7d5926e9cc6c9 100644
--- a/docs/reference/docs/delete-by-query.asciidoc
+++ b/docs/reference/docs/delete-by-query.asciidoc
@@ -209,7 +209,9 @@ include::{es-repo-dir}/rest-api/common-parms.asciidoc[tag=search-q]
 
 include::{es-repo-dir}/rest-api/common-parms.asciidoc[tag=request_cache]
 
-include::{es-repo-dir}/rest-api/common-parms.asciidoc[tag=refresh]
+`refresh`::
+(Optional, Boolean) If `true`, {es} refreshes all shards involved in the
+delete by query after the request completes. Defaults to `false`.
 
 include::{es-repo-dir}/rest-api/common-parms.asciidoc[tag=requests_per_second]
 
diff --git a/docs/reference/docs/get.asciidoc b/docs/reference/docs/get.asciidoc
index ba9f0ef399ea5..4603cdb90d27e 100644
--- a/docs/reference/docs/get.asciidoc
+++ b/docs/reference/docs/get.asciidoc
@@ -167,9 +167,8 @@ include::{es-repo-dir}/rest-api/common-parms.asciidoc[tag=preference]
 include::{es-repo-dir}/rest-api/common-parms.asciidoc[tag=realtime]
 
 `refresh`::
-(Optional, Boolean)
-If `true`, {es} refreshes the affected shards to make this operation visible to
-search. If `false`, do nothing with refreshes. Defaults to `false`.
+(Optional, Boolean) If `true`, the request refreshes the relevant shard before
+retrieving the document. Defaults to `false`.
 
 include::{es-repo-dir}/rest-api/common-parms.asciidoc[tag=routing]
 
diff --git a/docs/reference/docs/multi-get.asciidoc b/docs/reference/docs/multi-get.asciidoc
index 61bb506454ebc..44c3a230fe52e 100644
--- a/docs/reference/docs/multi-get.asciidoc
+++ b/docs/reference/docs/multi-get.asciidoc
@@ -68,7 +68,9 @@ include::{es-repo-dir}/rest-api/common-parms.asciidoc[tag=preference]
 
 include::{es-repo-dir}/rest-api/common-parms.asciidoc[tag=realtime]
 
-include::{es-repo-dir}/rest-api/common-parms.asciidoc[tag=refresh]
+`refresh`::
+(Optional, Boolean) If `true`, the request refreshes relevant shards before
+retrieving documents. Defaults to `false`.
 
 include::{es-repo-dir}/rest-api/common-parms.asciidoc[tag=routing]
 
diff --git a/docs/reference/docs/reindex.asciidoc b/docs/reference/docs/reindex.asciidoc
index 69d0ea8334be6..846893f8b0d33 100644
--- a/docs/reference/docs/reindex.asciidoc
+++ b/docs/reference/docs/reindex.asciidoc
@@ -466,7 +466,9 @@ POST _reindex
 [[docs-reindex-api-query-params]]
 ==== {api-query-parms-title}
 
-include::{es-repo-dir}/rest-api/common-parms.asciidoc[tag=refresh]
+`refresh`::
+(Optional, Boolean) If `true`, the request refreshes affected shards to make
+this operation visible to search. Defaults to `false`.
 
 `timeout`::
 +