From dd3813170466b77a5168ba82b804eeaf6db60c1a Mon Sep 17 00:00:00 2001
From: Haojian Wu <hokein.wu@gmail.com>
Date: Sun, 20 Sep 2015 19:08:31 +0800
Subject: [PATCH] :memo: Add DownloadItem doc.

---
 docs/api/download-item.md | 83 +++++++++++++++++++++++++++++++++++++++
 docs/api/session.md       | 15 ++++---
 2 files changed, 92 insertions(+), 6 deletions(-)
 create mode 100644 docs/api/download-item.md

diff --git a/docs/api/download-item.md b/docs/api/download-item.md
new file mode 100644
index 000000000..eacff6294
--- /dev/null
+++ b/docs/api/download-item.md
@@ -0,0 +1,83 @@
+# DownloadItem
+
+`DownloadItem` is an EventEmitter represents a download item in Electron. It
+is used in `will-download` event of `Session` module, and allows users to
+control the download item.
+
+```javascript
+// Disable showing the download saving dialog.
+win.webContents.session.setOpenDownloadDialog(false);
+
+win.webContents.session.on('will-download', function(event, item, webContents) {
+  console.log("Download from " + item.getURL());
+  console.log(item.getMimeType());
+  console.log(item.getSuggestedFilename());
+  console.log(item.getTotalBytes());
+  item.on('updated', function() {
+    console.log('Recived bytes: ' + item.getReceiveBytes());
+  });
+  item.on('completed', function() {
+    if (item.getReceiveBytes() >= item.getTotalBytes()) {
+      console.log("Download successfully");
+    } else {
+      console.log("Download is cancelled or interrupted that can't be resumed");
+    }
+  });
+```
+
+
+## Events
+
+### Event: 'updated'
+
+Emits when the `downloadItem` gets updated.
+
+### Event: 'completed'
+
+Emits when the download is in a terminal state. This includes a completed
+download, a cancelled download(via `downloadItem.cancel()`), and interrputed
+download that can't be resumed.
+
+## Methods
+
+The `downloadItem` object has the following methods:
+
+### `downloadItem.pause()`
+
+Pauses the download.
+
+### `downloadItem.resume()`
+
+Resumes the download that has been paused.
+
+### `downloadItem.cancel()`
+
+Cancels the download operation.
+
+### `downloadItem.getURL()`
+
+Returns a `String` represents the origin url where the item is downloaded from.
+
+### `downloadItem.getMimeType()`
+
+Returns a `String` represents the mime type.
+
+### `downloadItem.hasUserGesture()`
+
+Returns a `Boolean` indicates whether the download has user gesture.
+
+### `downloadItem.getSuggestedFilename()`
+
+Returns a `String` represents the suggested file name of the download file.
+
+**Note:** The suggested file name is not always the same as the actual one saved
+in local disk. If user changes the file name in a prompted download saving
+dialog, the actual name of saved file will be different with the suggested one.
+
+### `downloadItem.getTotalBytes()`
+
+Returns a `Integer` represents the total size in bytes of the download item.
+
+### `downloadItem.getReceivedBytes()`
+
+Returns a `Integer` represents the received bytes of the download item.
diff --git a/docs/api/session.md b/docs/api/session.md
index 439cf8514..2219cf3be 100644
--- a/docs/api/session.md
+++ b/docs/api/session.md
@@ -18,11 +18,7 @@ var session = win.webContents.session
 ### Event: 'will-download'
 
 * `event` Event
-* `item` Object
-  * `url` String
-  * `filename` String
-  * `mimeType` String
-  * `hasUserGesture` Boolean
+* `item` [DownloadItem](download-item.md)
 * `webContents` [WebContents](web-contents.md)
 
 Fired when Electron is about to download `item` in `webContents`.
@@ -32,7 +28,7 @@ Calling `event.preventDefault()` will cancel the download.
 ```javascript
 session.on('will-download', function(event, item, webContents) {
   event.preventDefault();
-  require('request')(item.url, function(data) {
+  require('request')(item.getURL(), function(data) {
     require('fs').writeFileSync('/somewhere', data);
   });
 });
@@ -195,3 +191,10 @@ proxy-uri = [<proxy-scheme>"://"]<proxy-host>[":"<proxy-port>]
 
 Sets download saving directory. By default, the download directory will be the
 `Downloads` under the respective app folder.
+
+### `session.setOpenDownloadDialog(openDownloadDialog)`
+
+* `openDownloadDialog` Boolean - Whether a download saving dialog will be
+  prompted when the download starts.
+
+By default, the download saving dialog is enable in Electron.
-- 
2.34.1