docs: New session methods

docs/api/session.md

@@ -1,8 +1,10 @@
 # session
 
-The `session` object is a property of [`webContents`](web-contents.md) which is
+The `session` module can be used to create new `Session` objects.
-a property of [`BrowserWindow`](browser-window.md). You can access it through an
+
-instance of `BrowserWindow`. For example:
+You can also access the `session` of existing pages by using the `session`
+property of [`webContents`](web-contents.md) which is a property of
+[`BrowserWindow`](browser-window.md).
 
 ```javascript
 const BrowserWindow = require('electron').BrowserWindow;
@@ -10,12 +12,47 @@ const BrowserWindow = require('electron').BrowserWindow;
 var win = new BrowserWindow({ width: 800, height: 600 });
 win.loadURL("http://github.com");
 
-var session = win.webContents.session
+var ses = win.webContents.session
 ```
 
-## Events
+## Methods
 
-### Event: 'will-download'
+The `session` module has the following methods:
+
+### session.fromPartition(partition)
+
+* `partition` String
+
+Returns a new `Session` instance from `partition` string.
+
+If `partition` starts with `persist:`, the page will use a persistent session
+available to all pages in the app with the same `partition`. if there is no
+`persist:` prefix, the page will use an in-memory session. If the `partition` is
+empty then default session of the app will be returned.
+
+## Properties
+
+The `session` module has the following properties:
+
+### session.defaultSession
+
+Returns the default session object of the app.
+
+## Class: Session
+
+You can create a `Session` object in the `session` module:
+
+```javascript
+const session = require('electron').session;
+
+var ses = session.fromPartition('persist:name');
+```
+
+### Instance Events
+
+The following events are available on instances of `Session`:
+
+#### Event: 'will-download'
 
 * `event` Event
 * `item` [DownloadItem](download-item.md)
@@ -34,11 +71,11 @@ session.on('will-download', function(event, item, webContents) {
 });
 ```
 
-## Methods
+### Instance Methods
 
-The `session` object has the following methods:
+The following methods are available on instances of `Session`:
 
-### `session.cookies`
+#### `ses.cookies`
 
 The `cookies` gives you ability to query and modify cookies. For example:
 
@@ -74,7 +111,7 @@ win.webContents.on('did-finish-load', function() {
 });
 ```
 
-### `session.cookies.get(details, callback)`
+#### `ses.cookies.get(details, callback)`
 
 `details` Object, properties:
 
@@ -102,7 +139,7 @@ win.webContents.on('did-finish-load', function() {
      the number of seconds since the UNIX epoch. Not provided for session
      cookies.
 
-### `session.cookies.set(details, callback)`
+#### `ses.cookies.set(details, callback)`
 
 `details` Object, properties:
 
@@ -121,23 +158,23 @@ win.webContents.on('did-finish-load', function() {
 * `callback` Function - function(error)
   * `error` Error
 
-### `session.cookies.remove(details, callback)`
+#### `ses.cookies.remove(details, callback)`
 
-* `details` Object, proprties:
+* `details` Object
   * `url` String - The URL associated with the cookie
   * `name` String - The name of cookie to remove
 * `callback` Function - function(error)
   * `error` Error
 
-### `session.clearCache(callback)`
+#### `ses.clearCache(callback)`
 
 * `callback` Function - Called when operation is done
 
 Clears the session’s HTTP cache.
 
-### `session.clearStorageData([options, ]callback)`
+#### `ses.clearStorageData([options, ]callback)`
 
-* `options` Object (optional), proprties:
+* `options` Object (optional)
   * `origin` String - Should follow `window.location.origin`’s representation
     `scheme://host:port`.
   * `storages` Array - The types of storages to clear, can contain:
@@ -149,7 +186,7 @@ Clears the session’s HTTP cache.
 
 Clears the data of web storages.
 
-### `session.setProxy(config, callback)`
+#### `ses.setProxy(config, callback)`
 
 * `config` String
 * `callback` Function - Called when operation is done.
@@ -187,14 +224,14 @@ proxy-uri = [<proxy-scheme>"://"]<proxy-host>[":"<proxy-port>]
                                       URLs.
 ```
 
-### `session.setDownloadPath(path)`
+#### `ses.setDownloadPath(path)`
 
 * `path` String - The download location
 
 Sets download saving directory. By default, the download directory will be the
 `Downloads` under the respective app folder.
 
-### `session.enableNetworkEmulation(options)`
+#### `ses.enableNetworkEmulation(options)`
 
 * `options` Object
   * `offline` Boolean - Whether to emulate network outage.
@@ -216,12 +253,12 @@ window.webContents.session.enableNetworkEmulation({
 window.webContents.session.enableNetworkEmulation({offline: true});
 ```
 
-### `session.disableNetworkEmulation`
+#### `ses.disableNetworkEmulation()`
 
 Disables any network emulation already active for the `session`. Resets to
 the original network configuration.
 
-### `session.setCertificateVerifyProc(proc)`
+#### `ses.setCertificateVerifyProc(proc)`
 
 * `proc` Function