docs: Improve the cookies docs

diff --git a/docs/api/session.md b/docs/api/session.md
index d1db7e3..dcd6744 100644 (file)
--- a/docs/api/session.md
+++ b/docs/api/session.md
@@ -63,7 +63,7 @@ Emitted when Electron is about to download `item` in `webContents`.
 Calling `event.preventDefault()` will cancel the download.
 
 ```javascript
-session.on('will-download', function(event, item, webContents) {
+session.defaultSession.on('will-download', function(event, item, webContents) {
   event.preventDefault();
   require('request')(item.getURL(), function(data) {
     require('fs').writeFileSync('/somewhere', data);
@@ -80,91 +80,84 @@ The following methods are available on instances of `Session`:
 The `cookies` gives you ability to query and modify cookies. For example:
 
 ```javascript
-const BrowserWindow = require('electron').BrowserWindow;
+// Query all cookies.
+session.defaultSession.cookies.get({}, function(error, cookies) {
+  console.log(cookies);
+});
 
-var win = new BrowserWindow({ width: 800, height: 600 });
+// Query all cookies associated with a specific url.
+session.defaultSession.cookies.get({ url : "http://www.github.com" }, function(error, cookies) {
+  console.log(cookies);
+});
 
-win.loadURL('https://github.com');
+// Set a cookie with the given cookie data;
+// may overwrite equivalent cookies if they exist.
+var cookie = { url : "http://www.github.com", name : "dummy_name", value : "dummy" };
+session.defaultSession.cookies.set(cookie, function(error) {
+  if (error)
+    console.error(error);
+});
+```
 
-win.webContents.on('did-finish-load', function() {
-  // Query all cookies.
-  win.webContents.session.cookies.get({}, function(error, cookies) {
-    if (error) throw error;
-    console.log(cookies);
-  });
+#### `ses.cookies.get(filter, callback)`
 
-  // Query all cookies associated with a specific url.
-  win.webContents.session.cookies.get({ url : "http://www.github.com" },
-      function(error, cookies) {
-        if (error) throw error;
-        console.log(cookies);
-  });
+* `filter` Object
+  * `url` String __optional__ - Retrieves cookies which are associated with
+    `url`. Empty implies retrieving cookies of all urls.
+  * `name` String __optional__ - Filters cookies by name.
+  * `domain` String __optional__ - Retrieves cookies whose domains match or are
+    subdomains of `domains`
+  * `path` String __optional__ - Retrieves cookies whose path matches `path`.
+  * `secure` Boolean __optional__ - Filters cookies by their Secure property.
+  * `session` Boolean __optional__ - Filters out session or persistent cookies.
+* `callback` Function
 
-  // Set a cookie with the given cookie data;
-  // may overwrite equivalent cookies if they exist.
-  win.webContents.session.cookies.set(
-    { url : "http://www.github.com", name : "dummy_name", value : "dummy"},
-    function(error, cookies) {
-      if (error) throw error;
-      console.log(cookies);
-  });
-});
-```
+Sends a request to get all cookies matching `details`, `callback` will be called
+with `callback(error, cookies)` on complete.
+
+`cookies` is an Array of `cookie` objects.
 
-#### `ses.cookies.get(details, callback)`
-
-`details` Object, properties:
-
-* `url` String - Retrieves cookies which are associated with `url`.
-  Empty implies retrieving cookies of all urls.
-* `name` String - Filters cookies by name
-* `domain` String - Retrieves cookies whose domains match or are subdomains of
-  `domains`
-* `path` String - Retrieves cookies whose path matches `path`
-* `secure` Boolean - Filters cookies by their Secure property
-* `session` Boolean - Filters out session or persistent cookies.
-* `callback` Function - function(error, cookies)
-* `error` Error
-* `cookies` Array - array of `cookie` objects, properties:
+* `cookie` Object
   *  `name` String - The name of the cookie.
   *  `value` String - The value of the cookie.
   *  `domain` String - The domain of the cookie.
-  *  `host_only` String - Whether the cookie is a host-only cookie.
+  *  `hostOnly` String - Whether the cookie is a host-only cookie.
   *  `path` String - The path of the cookie.
-  *  `secure` Boolean - Whether the cookie is marked as Secure (typically HTTPS).
-  *  `http_only` Boolean - Whether the cookie is marked as HttpOnly.
+  *  `secure` Boolean - Whether the cookie is marked as secure.
+  *  `httpOnly` Boolean - Whether the cookie is marked as HTTP only.
   *  `session` Boolean - Whether the cookie is a session cookie or a persistent
      cookie with an expiration date.
-  *  `expirationDate` Double - (Option) The expiration date of the cookie as
+  *  `expirationDate` Double __optional__ - The expiration date of the cookie as
      the number of seconds since the UNIX epoch. Not provided for session
      cookies.
 
 #### `ses.cookies.set(details, callback)`
 
-`details` Object, properties:
+* `details` Object
+  * `url` String - Retrieves cookies which are associated with `url`
+  * `name` String - The name of the cookie. Empty by default if omitted.
+  * `value` String - The value of the cookie. Empty by default if omitted.
+  * `domain` String - The domain of the cookie. Empty by default if omitted.
+  * `path` String - The path of the cookie. Empty by default if omitted.
+  * `secure` Boolean - Whether the cookie should be marked as Secure. Defaults to
+    false.
+  * `session` Boolean - Whether the cookie should be marked as HttpOnly. Defaults
+    to false.
+  * `expirationDate` Double -  The expiration date of the cookie as the number of
+    seconds since the UNIX epoch. If omitted, the cookie becomes a session cookie.
+* `callback` Function
 
-* `url` String - Retrieves cookies which are associated with `url`
-* `name` String - The name of the cookie. Empty by default if omitted.
-* `value` String - The value of the cookie. Empty by default if omitted.
-* `domain` String - The domain of the cookie. Empty by default if omitted.
-* `path` String - The path of the cookie. Empty by default if omitted.
-* `secure` Boolean - Whether the cookie should be marked as Secure. Defaults to
-  false.
-* `session` Boolean - Whether the cookie should be marked as HttpOnly. Defaults
-  to false.
-* `expirationDate` Double -    The expiration date of the cookie as the number of
-  seconds since the UNIX epoch. If omitted, the cookie becomes a session cookie.
+Sets the cookie with `details`, `callback` will be called with `callback(error)`
+on complete.
 
-* `callback` Function - function(error)
-  * `error` Error
+#### `ses.cookies.remove(url, name, callback)`
 
-#### `ses.cookies.remove(details, callback)`
+* `url` String - The URL associated with the cookie.
+* `name` String - The name of cookie to remove.
+* `callback` Function
 
-* `details` Object
-  * `url` String - The URL associated with the cookie
-  * `name` String - The name of cookie to remove
-* `callback` Function - function(error)
-  * `error` Error
+Removes the cookies matching `url` and `name`, `callback` will called with
+`callback()` on complete.
 
 #### `ses.clearCache(callback)`