From 45d3842214c273b3e294cc8d97004fd06890b6aa Mon Sep 17 00:00:00 2001
From: Igor Motov <igor@motovs.org>
Date: Wed, 8 Oct 2014 08:43:06 -0400
Subject: [PATCH] Docs: clarify wait_for_completion flag in snapshot
 documentation

Closes #7952
---
 docs/reference/modules/snapshots.asciidoc              | 10 +++++++---
 .../snapshots/create/CreateSnapshotRequest.java        |  7 +++++--
 2 files changed, 12 insertions(+), 5 deletions(-)

diff --git a/docs/reference/modules/snapshots.asciidoc b/docs/reference/modules/snapshots.asciidoc
index 00de9ec164d..03a971d497f 100644
--- a/docs/reference/modules/snapshots.asciidoc
+++ b/docs/reference/modules/snapshots.asciidoc
@@ -119,9 +119,13 @@ command:
 $ curl -XPUT "localhost:9200/_snapshot/my_backup/snapshot_1?wait_for_completion=true"
 -----------------------------------
 
-The `wait_for_completion` parameter specifies whether or not the request should return immediately or wait for snapshot
-completion. By default snapshot of all open and started indices in the cluster is created. This behavior can be changed
-by specifying the list of indices in the body of the snapshot request.
+The `wait_for_completion` parameter specifies whether or not the request should return immediately after snapshot
+initialization (default) or wait for snapshot completion. During snapshot initialization, information about all
+previous snapshots is loaded into the memory, which means that in large repositories it may take several seconds (or
+even minutes) for this command to return even if the `wait_for_completion` parameter is set to `false`.
+
+By default snapshot of all open and started indices in the cluster is created. This behavior can be changed by
+specifying the list of indices in the body of the snapshot request.
 
 [source,js]
 -----------------------------------
diff --git a/src/main/java/org/elasticsearch/action/admin/cluster/snapshots/create/CreateSnapshotRequest.java b/src/main/java/org/elasticsearch/action/admin/cluster/snapshots/create/CreateSnapshotRequest.java
index 0d878a4a4bd..f999740624d 100644
--- a/src/main/java/org/elasticsearch/action/admin/cluster/snapshots/create/CreateSnapshotRequest.java
+++ b/src/main/java/org/elasticsearch/action/admin/cluster/snapshots/create/CreateSnapshotRequest.java
@@ -245,9 +245,12 @@ public class CreateSnapshotRequest extends MasterNodeOperationRequest<CreateSnap
     }
 
     /**
-     * If set to true the request should wait for the snapshot completion before returning.
+     * If set to true the operation should wait for the snapshot completion before returning.
      *
-     * @param waitForCompletion true if
+     * By default, the operation will return as soon as snapshot is initialized. It can be changed by setting this
+     * flag to true.
+     *
+     * @param waitForCompletion true if operation should wait for the snapshot completion
      * @return this request
      */
     public CreateSnapshotRequest waitForCompletion(boolean waitForCompletion) {