From aae8cc839a0c41060507402b23ce3c33e1ae3784 Mon Sep 17 00:00:00 2001
From: Yury Semikhatsky <yurys@chromium.org>
Date: Mon, 8 Mar 2021 19:52:07 -0800
Subject: [PATCH] docs: improve Download methods documentation (#5760)

---
 docs/src/api/class-download.md | 10 ++++++----
 types/types.d.ts               |  9 +++++----
 2 files changed, 11 insertions(+), 8 deletions(-)

diff --git a/docs/src/api/class-download.md b/docs/src/api/class-download.md
index 0142ca9ed6..41859c8731 100644
--- a/docs/src/api/class-download.md
+++ b/docs/src/api/class-download.md
@@ -62,21 +62,23 @@ Returns readable stream for current download or `null` if download failed.
 
 ## async method: Download.delete
 
-Deletes the downloaded file.
+Deletes the downloaded file. Will wait for the download to finish if necessary.
 
 ## async method: Download.failure
 - returns: <[null]|[string]>
 
-Returns download error if any.
+Returns download error if any. Will wait for the download to finish if necessary.
 
 ## async method: Download.path
 - returns: <[null]|[path]>
 
-Returns path to the downloaded file in case of successful download.
+Returns path to the downloaded file in case of successful download. The method will
+wait for the download to finish if necessary.
 
 ## async method: Download.saveAs
 
-Saves the download to a user-specified path.
+Saves the download to a user-specified path. It is safe to call this method while the download
+is still in progress.
 
 ### param: Download.saveAs.path
 - `path` <[path]>
diff --git a/types/types.d.ts b/types/types.d.ts
index 16af598d48..3d1e06ab4f 100644
--- a/types/types.d.ts
+++ b/types/types.d.ts
@@ -9124,22 +9124,23 @@ export interface Download {
   createReadStream(): Promise<null|Readable>;
 
   /**
-   * Deletes the downloaded file.
+   * Deletes the downloaded file. Will wait for the download to finish if necessary.
    */
   delete(): Promise<void>;
 
   /**
-   * Returns download error if any.
+   * Returns download error if any. Will wait for the download to finish if necessary.
    */
   failure(): Promise<null|string>;
 
   /**
-   * Returns path to the downloaded file in case of successful download.
+   * Returns path to the downloaded file in case of successful download. The method will wait for the download to finish if
+   * necessary.
    */
   path(): Promise<null|string>;
 
   /**
-   * Saves the download to a user-specified path.
+   * Saves the download to a user-specified path. It is safe to call this method while the download is still in progress.
    * @param path Path where the download should be saved.
    */
   saveAs(path: string): Promise<void>;