Docs: clarify wait_for_completion flag in snapshot documentation

Closes #7952

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]
 -----------------------------------

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) {