From 3d371e09b70176cd346768b68480b8a60394d5a7 Mon Sep 17 00:00:00 2001
From: Zeke Sikelianos <zeke@sikelianos.com>
Date: Mon, 22 Aug 2016 14:11:03 -0700
Subject: [PATCH 1/2] add a blockquote for every class

---
 docs/api/native-image.md |  2 +-
 docs/api/session.md      | 23 ++++++++++++++---------
 docs/api/web-contents.md | 11 ++++++++---
 3 files changed, 23 insertions(+), 13 deletions(-)

diff --git a/docs/api/native-image.md b/docs/api/native-image.md
index 947a5b77b038..0e16e30ee1ee 100644
--- a/docs/api/native-image.md
+++ b/docs/api/native-image.md
@@ -145,7 +145,7 @@ Creates a new `NativeImage` instance from `dataURL`.
 
 ## Class: NativeImage
 
-A native wrapper for images such as tray, dock, and application icons.
+> Natively wrap images such as tray, dock, and application icons.
 
 ### Instance Methods
 
diff --git a/docs/api/session.md b/docs/api/session.md
index 0df56c55d5f1..03b669ceb0ba 100644
--- a/docs/api/session.md
+++ b/docs/api/session.md
@@ -50,6 +50,8 @@ Returns the default session object of the app.
 
 ## Class: Session
 
+> Get and set properties of a session.
+
 You can create a `Session` object in the `session` module:
 
 ```javascript
@@ -353,8 +355,10 @@ app.on('ready', function () {
 
 ## Class: Cookies
 
-The `Cookies` class gives you ability to query and modify cookies. Instances of
-`Cookies` class must be received by using `cookies` property of `Session` class.
+> Query and modify a session's cookies.
+
+Instances of the `Cookies` class must be received by using `cookies` property of
+`Session` class.
 
 For example:
 
@@ -446,21 +450,22 @@ Removes the cookies matching `url` and `name`, `callback` will called with
 
 ## Class: WebRequest
 
-The `WebRequest` class allows to intercept and modify contents of a request at
-various stages of its lifetime. Instances of `WebRequest` class must be received
-by using `webRequest` property of `Session` class.
+> Intercept and modify the contents of a request at various stages of its lifetime.
 
-The methods of `WebRequest` accept an optional `filter` and a `listener`, the
+Instances of the `WebRequest` class must be received by using the `webRequest`
+property of the `Session` class.
+
+The methods of `WebRequest` accept an optional `filter` and a `listener`. The
 `listener` will be called with `listener(details)` when the API's event has
-happened, the `details` is an object that describes the request. Passing `null`
+happened. The `details` object describes the request. Passing `null`
 as `listener` will unsubscribe from the event.
 
-The `filter` is an object that has an `urls` property, which is an Array of URL
+The `filter` object has a `urls` property which is an Array of URL
 patterns that will be used to filter out the requests that do not match the URL
 patterns. If the `filter` is omitted then all requests will be matched.
 
 For certain events the `listener` is passed with a `callback`, which should be
-called with an `response` object when `listener` has done its work.
+called with a `response` object when `listener` has done its work.
 
 An example of adding `User-Agent` header for requests:
 
diff --git a/docs/api/web-contents.md b/docs/api/web-contents.md
index a83744babd61..47c58919c750 100644
--- a/docs/api/web-contents.md
+++ b/docs/api/web-contents.md
@@ -29,8 +29,8 @@ console.log(webContents)
 
 ### `webContents.getAllWebContents()`
 
-Returns an array of all web contents. This will contain web contents for all
-windows, webviews, opened devtools, and devtools extension background pages.
+Returns an array of all `WebContents` instances. This will contain web contents
+for all windows, webviews, opened devtools, and devtools extension background pages.
 
 ### `webContents.getFocusedWebContents()`
 
@@ -39,6 +39,8 @@ returns `null`.
 
 ## Class: WebContents
 
+> Render and control the contents of a BrowserWindow instance.
+
 ### Instance Events
 
 #### Event: 'did-finish-load'
@@ -1162,7 +1164,10 @@ Get the debugger instance for this webContents.
 
 ## Class: Debugger
 
-Debugger API serves as an alternate transport for [remote debugging protocol][rdp].
+> An alternate transport for Chrome's remote debugging protocol.
+
+Chrome Developer Tools has a [special binding][rdp] available at JavaScript
+runtime that allows interacting with pages and instrumenting them.
 
 ```javascript
 const {BrowserWindow} = require('electron')

From 098d4dc0caf17473db15a50e9069efb2e9e8b883 Mon Sep 17 00:00:00 2001
From: Zeke Sikelianos <zeke@sikelianos.com>
Date: Mon, 22 Aug 2016 21:45:25 -0700
Subject: [PATCH 2/2] improve wording about class instantiation

---
 docs/api/session.md | 8 ++++----
 1 file changed, 4 insertions(+), 4 deletions(-)

diff --git a/docs/api/session.md b/docs/api/session.md
index 03b669ceb0ba..0d5bad9e0f1e 100644
--- a/docs/api/session.md
+++ b/docs/api/session.md
@@ -357,8 +357,8 @@ app.on('ready', function () {
 
 > Query and modify a session's cookies.
 
-Instances of the `Cookies` class must be received by using `cookies` property of
-`Session` class.
+Instances of the `Cookies` class are accessed by using `cookies` property of
+a `Session`.
 
 For example:
 
@@ -452,8 +452,8 @@ Removes the cookies matching `url` and `name`, `callback` will called with
 
 > Intercept and modify the contents of a request at various stages of its lifetime.
 
-Instances of the `WebRequest` class must be received by using the `webRequest`
-property of the `Session` class.
+Instances of the `WebRequest` class are accessed by using the `webRequest`
+property of a `Session`.
 
 The methods of `WebRequest` accept an optional `filter` and a `listener`. The
 `listener` will be called with `listener(details)` when the API's event has