From ee190ca62aa0595b23396544667dcc63bb83667c Mon Sep 17 00:00:00 2001
From: Zeke Sikelianos <zeke@sikelianos.com>
Date: Thu, 21 Apr 2016 15:35:29 -0700
Subject: [PATCH 1/4] create a one-liner description for each API

---
 docs/api/accelerator.md                  | 6 ++++--
 docs/api/app.md                          | 2 +-
 docs/api/auto-updater.md                 | 4 +++-
 docs/api/browser-window.md               | 3 +--
 docs/api/chrome-command-line-switches.md | 9 +++++----
 docs/api/clipboard.md                    | 3 ++-
 docs/api/content-tracing.md              | 5 +++--
 docs/api/crash-reporter.md               | 2 +-
 docs/api/desktop-capturer.md             | 4 ++--
 docs/api/dialog.md                       | 4 +---
 docs/api/download-item.md                | 2 ++
 docs/api/environment-variables.md        | 2 ++
 docs/api/file-object.md                  | 2 ++
 docs/api/frameless-window.md             | 2 ++
 docs/api/global-shortcut.md              | 2 ++
 docs/api/ipc-main.md                     | 2 ++
 docs/api/ipc-renderer.md                 | 2 ++
 docs/api/menu-item.md                    | 3 +--
 docs/api/menu.md                         | 5 ++---
 docs/api/native-image.md                 | 2 ++
 docs/api/power-monitor.md                | 5 +++--
 docs/api/power-save-blocker.md           | 4 +---
 docs/api/process.md                      | 2 ++
 docs/api/protocol.md                     | 4 ++--
 docs/api/remote.md                       | 2 ++
 docs/api/screen.md                       | 7 ++++---
 docs/api/session.md                      | 2 ++
 docs/api/shell.md                        | 2 ++
 docs/api/synopsis.md                     | 2 ++
 docs/api/tray.md                         | 3 +--
 docs/api/web-contents.md                 | 3 ++-
 docs/api/web-frame.md                    | 3 +--
 docs/api/web-view-tag.md                 | 2 ++
 docs/api/window-open.md                  | 2 ++
 34 files changed, 70 insertions(+), 39 deletions(-)

diff --git a/docs/api/accelerator.md b/docs/api/accelerator.md
index 83d8d3a7c2..ff2b8190a9 100644
--- a/docs/api/accelerator.md
+++ b/docs/api/accelerator.md
@@ -1,7 +1,9 @@
 # Accelerator
 
-An accelerator is a string that represents a keyboard shortcut. It can contain
-multiple modifiers and key codes, combined by the `+` character.
+Define keyboard shortcuts.
+
+Accelerators can contain multiple modifiers and key codes, combined by
+the `+` character.
 
 Examples:
 
diff --git a/docs/api/app.md b/docs/api/app.md
index 54e40263ea..b06f8e6b6a 100644
--- a/docs/api/app.md
+++ b/docs/api/app.md
@@ -1,6 +1,6 @@
 # app
 
-The `app` module is responsible for controlling the application's lifecycle.
+Control your application's event lifecycle.
 
 The following example shows how to quit the application when the last window is
 closed:
diff --git a/docs/api/auto-updater.md b/docs/api/auto-updater.md
index dccae1212a..daea501210 100644
--- a/docs/api/auto-updater.md
+++ b/docs/api/auto-updater.md
@@ -1,6 +1,8 @@
 # autoUpdater
 
-This module provides an interface for the `Squirrel` auto-updater framework.
+Enable apps to update themselves automatically.
+
+The `autoUpdater` module provides and interface for the [Squirrel](https://github.com/Squirrel) framework.
 
 You can quickly launch a multi-platform release server for distributing your
 application by using one of these projects:
diff --git a/docs/api/browser-window.md b/docs/api/browser-window.md
index c249728152..b7536249f8 100644
--- a/docs/api/browser-window.md
+++ b/docs/api/browser-window.md
@@ -1,7 +1,6 @@
 # BrowserWindow
 
-The `BrowserWindow` class gives you the ability to create a browser window. For
-example:
+Create and control browser windows.
 
 ```javascript
 // In the main process.
diff --git a/docs/api/chrome-command-line-switches.md b/docs/api/chrome-command-line-switches.md
index 8e8aa38e62..f7515a5f1f 100644
--- a/docs/api/chrome-command-line-switches.md
+++ b/docs/api/chrome-command-line-switches.md
@@ -1,9 +1,10 @@
 # Supported Chrome command line switches
 
-This page lists the command line switches used by the Chrome browser that are
-also supported by Electron. You can use
-[app.commandLine.appendSwitch][append-switch] to append them in your app's main
-script before the [ready][ready] event of [app][app] module is emitted:
+Command line switches supported by Electron.
+
+You can use [app.commandLine.appendSwitch][append-switch] to append them in
+your app's main script before the [ready][ready] event of [app][app] module is
+emitted:
 
 ```javascript
 const app = require('electron').app;
diff --git a/docs/api/clipboard.md b/docs/api/clipboard.md
index 7f95a1af26..2f9440f80e 100644
--- a/docs/api/clipboard.md
+++ b/docs/api/clipboard.md
@@ -1,6 +1,7 @@
 # clipboard
 
-The `clipboard` module provides methods to perform copy and paste operations.
+Perform copy and paste operations on the system clipboard.
+
 The following example shows how to write a string to the clipboard:
 
 ```javascript
diff --git a/docs/api/content-tracing.md b/docs/api/content-tracing.md
index 0b83c2759c..66c7679dd0 100644
--- a/docs/api/content-tracing.md
+++ b/docs/api/content-tracing.md
@@ -1,7 +1,8 @@
 # contentTracing
 
-The `content-tracing` module is used to collect tracing data generated by the
-underlying Chromium content module. This module does not include a web interface
+Debug your application using Chromium's content module.
+
+This module does not include a web interface
 so you need to open `chrome://tracing/` in a Chrome browser and load the
 generated file to view the result.
 
diff --git a/docs/api/crash-reporter.md b/docs/api/crash-reporter.md
index 9b7141e364..0ef2317db6 100644
--- a/docs/api/crash-reporter.md
+++ b/docs/api/crash-reporter.md
@@ -1,6 +1,6 @@
 # crashReporter
 
-The `crash-reporter` module enables sending your app's crash reports.
+Submit crash reports to a remote server.
 
 The following is an example of automatically submitting a crash report to a
 remote server:
diff --git a/docs/api/desktop-capturer.md b/docs/api/desktop-capturer.md
index b39a09e5aa..c80928017a 100644
--- a/docs/api/desktop-capturer.md
+++ b/docs/api/desktop-capturer.md
@@ -1,7 +1,7 @@
 # desktopCapturer
 
-The `desktopCapturer` module can be used to get available sources that can be
-used to be captured with `getUserMedia`.
+Capture audio, video, and images from a microphone, camera, or
+screen using the `getUserMedia` API.
 
 ```javascript
 // In the renderer process.
diff --git a/docs/api/dialog.md b/docs/api/dialog.md
index 3eb0292a49..e052f10dca 100644
--- a/docs/api/dialog.md
+++ b/docs/api/dialog.md
@@ -1,8 +1,6 @@
 # dialog
 
-The `dialog` module provides APIs to show native system dialogs, such as opening
-files or alerting, so web applications can deliver the same user experience as
-native applications.
+Display native system dialogs for opening and saving files, alerting, etc.
 
 An example of showing a dialog to select multiple files and directories:
 
diff --git a/docs/api/download-item.md b/docs/api/download-item.md
index f117ffc57a..02e5b39500 100644
--- a/docs/api/download-item.md
+++ b/docs/api/download-item.md
@@ -1,5 +1,7 @@
 # DownloadItem
 
+Trigger file downloads from remote sources.
+
 `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.
diff --git a/docs/api/environment-variables.md b/docs/api/environment-variables.md
index 3483c19d64..6186c06904 100644
--- a/docs/api/environment-variables.md
+++ b/docs/api/environment-variables.md
@@ -1,5 +1,7 @@
 # Environment variables
 
+Control application configuration and behavior without changing code.
+
 Some behaviors of Electron are controlled by environment variables, because they
 are initialized earlier than command line and the app's code.
 
diff --git a/docs/api/file-object.md b/docs/api/file-object.md
index 01d49c3915..f1d3680eb8 100644
--- a/docs/api/file-object.md
+++ b/docs/api/file-object.md
@@ -1,5 +1,7 @@
 # `File` object
 
+Use the HTML5 `File` API to work natively with files on the filesystem.
+
 The DOM's File interface provides abstraction around native files in order to
 let users work on native files directly with the HTML5 file API. Electron has
 added a `path` attribute to the `File` interface which exposes the file's real
diff --git a/docs/api/frameless-window.md b/docs/api/frameless-window.md
index 8e1dd46ec5..12497db4da 100644
--- a/docs/api/frameless-window.md
+++ b/docs/api/frameless-window.md
@@ -1,5 +1,7 @@
 # Frameless Window
 
+> Open a window without toolbars, borders, or other graphical "chrome".
+
 A frameless window is a window that has no
 [chrome](https://developer.mozilla.org/en-US/docs/Glossary/Chrome), the parts of
 the window, like toolbars, that are not a part of the web page. These are
diff --git a/docs/api/global-shortcut.md b/docs/api/global-shortcut.md
index f20758406b..c1bce458c8 100644
--- a/docs/api/global-shortcut.md
+++ b/docs/api/global-shortcut.md
@@ -1,5 +1,7 @@
 # globalShortcut
 
+Detect keyboard events when the application does not have keyboard focus.
+
 The `globalShortcut` module can register/unregister a global keyboard shortcut
 with the operating system so that you can customize the operations for various
 shortcuts.
diff --git a/docs/api/ipc-main.md b/docs/api/ipc-main.md
index 84fbcfd5a7..1ddb0bb1c9 100644
--- a/docs/api/ipc-main.md
+++ b/docs/api/ipc-main.md
@@ -1,5 +1,7 @@
 # ipcMain
 
+Communicate asynchronously from the main process to renderer processes.
+
 The `ipcMain` module is an instance of the
 [EventEmitter](https://nodejs.org/api/events.html) class. When used in the main
 process, it handles asynchronous and synchronous messages sent from a renderer
diff --git a/docs/api/ipc-renderer.md b/docs/api/ipc-renderer.md
index 46a2331af4..8d18524d1c 100644
--- a/docs/api/ipc-renderer.md
+++ b/docs/api/ipc-renderer.md
@@ -1,5 +1,7 @@
 # ipcRenderer
 
+Communicate asynchronously from a renderer process to the main process.
+
 The `ipcRenderer` module is an instance of the
 [EventEmitter](https://nodejs.org/api/events.html) class. It provides a few
 methods so you can send synchronous and asynchronous messages from the render
diff --git a/docs/api/menu-item.md b/docs/api/menu-item.md
index 1b36432ab2..5c5532289a 100644
--- a/docs/api/menu-item.md
+++ b/docs/api/menu-item.md
@@ -1,7 +1,6 @@
 # MenuItem
 
-The `menu-item` module allows you to add items to an application or context
-[`menu`](menu.md).
+Add items to application and context menus.
 
 See [`menu`](menu.md) for examples.
 
diff --git a/docs/api/menu.md b/docs/api/menu.md
index cb5a0cbe2d..6ac8a9ea1e 100644
--- a/docs/api/menu.md
+++ b/docs/api/menu.md
@@ -1,8 +1,7 @@
 # Menu
 
-The `menu` class is used to create native menus that can be used as
-application menus and
-[context menus](https://developer.mozilla.org/en-US/docs/Mozilla/Tech/XUL/PopupGuide/ContextMenus).
+Create native application menus and context menus.
+
 This module is a main process module which can be used in a render process via
 the `remote` module.
 
diff --git a/docs/api/native-image.md b/docs/api/native-image.md
index e0c3ae4662..ed3bbdacc9 100644
--- a/docs/api/native-image.md
+++ b/docs/api/native-image.md
@@ -1,5 +1,7 @@
 # nativeImage
 
+Create tray, dock, and application icons using PNG or JPG files.
+
 In Electron, for the APIs that take images, you can pass either file paths or
 `nativeImage` instances. An empty image will be used when `null` is passed.
 
diff --git a/docs/api/power-monitor.md b/docs/api/power-monitor.md
index 4465b253a7..72cfbca1f1 100644
--- a/docs/api/power-monitor.md
+++ b/docs/api/power-monitor.md
@@ -1,7 +1,8 @@
 # powerMonitor
 
-The `power-monitor` module is used to monitor power state changes. You can
-only use it in the main process. You should not use this module until the `ready`
+Monitor power state changes.
+
+You can only use it in the main process. You should not use this module until the `ready`
 event of the `app` module is emitted.
 
 For example:
diff --git a/docs/api/power-save-blocker.md b/docs/api/power-save-blocker.md
index a3ef798411..315bbdb9be 100644
--- a/docs/api/power-save-blocker.md
+++ b/docs/api/power-save-blocker.md
@@ -1,8 +1,6 @@
 # powerSaveBlocker
 
-The `powerSaveBlocker` module is used to block the system from entering
-low-power (sleep) mode and thus allowing the app to keep the system and screen
-active.
+Block the system from entering low-power (sleep) mode.
 
 For example:
 
diff --git a/docs/api/process.md b/docs/api/process.md
index 17c0be1092..1805337095 100644
--- a/docs/api/process.md
+++ b/docs/api/process.md
@@ -1,5 +1,7 @@
 # process
 
+Get information about the running application process.
+
 The `process` object in Electron has the following differences from the one in
 upstream node:
 
diff --git a/docs/api/protocol.md b/docs/api/protocol.md
index e57a34ef89..ade04c1cc3 100644
--- a/docs/api/protocol.md
+++ b/docs/api/protocol.md
@@ -1,7 +1,7 @@
 # protocol
 
-The `protocol` module can register a custom protocol or intercept an existing
-protocol.
+Register a custom protocol to intercept click events from other running
+applications.
 
 An example of implementing a protocol that has the same effect as the
 `file://` protocol:
diff --git a/docs/api/remote.md b/docs/api/remote.md
index 7bdbe0362f..fb585a0fc3 100644
--- a/docs/api/remote.md
+++ b/docs/api/remote.md
@@ -1,5 +1,7 @@
 # remote
 
+Communicate between the renderer process and the main process.
+
 The `remote` module provides a simple way to do inter-process communication
 (IPC) between the renderer process (web page) and the main process.
 
diff --git a/docs/api/screen.md b/docs/api/screen.md
index 90ef183a8a..5f8188f0d8 100644
--- a/docs/api/screen.md
+++ b/docs/api/screen.md
@@ -1,8 +1,9 @@
 # screen
 
-The `screen` module retrieves information about screen size, displays, cursor
-position, etc. You can not use this module until the `ready` event of the
-`app` module is emitted (by invoking or requiring it).
+> Retrieve information about screen size, displays, cursor position, etc.
+
+You cannot not use this module until the `ready` event of the `app` module is
+emitted (by invoking or requiring it).
 
 `screen` is an [EventEmitter](http://nodejs.org/api/events.html#events_class_events_eventemitter).
 
diff --git a/docs/api/session.md b/docs/api/session.md
index 9003018036..e7689c8e4b 100644
--- a/docs/api/session.md
+++ b/docs/api/session.md
@@ -1,5 +1,7 @@
 # session
 
+Manage browser cookies, cache, and other session data.
+
 The `session` module can be used to create new `Session` objects.
 
 You can also access the `session` of existing pages by using the `session`
diff --git a/docs/api/shell.md b/docs/api/shell.md
index 823dc481bb..b340acaebf 100644
--- a/docs/api/shell.md
+++ b/docs/api/shell.md
@@ -1,5 +1,7 @@
 # shell
 
+Manage files and URLs using their default applications.
+
 The `shell` module provides functions related to desktop integration.
 
 An example of opening a URL in the user's default browser:
diff --git a/docs/api/synopsis.md b/docs/api/synopsis.md
index 466b13828c..d79942531e 100644
--- a/docs/api/synopsis.md
+++ b/docs/api/synopsis.md
@@ -1,5 +1,7 @@
 # Synopsis
 
+Info about Node.js and the main and renderer processes.
+
 All of [Node.js's built-in modules](http://nodejs.org/api/) are available in
 Electron and third-party node modules also fully supported as well (including
 the [native modules](../tutorial/using-native-node-modules.md)).
diff --git a/docs/api/tray.md b/docs/api/tray.md
index aa972c57cd..d6bf2b3c73 100644
--- a/docs/api/tray.md
+++ b/docs/api/tray.md
@@ -1,7 +1,6 @@
 # Tray
 
-A `Tray` represents an icon in an operating system's notification area, it is
-usually attached with a context menu.
+Add icons and context menus to the system's notification area.
 
 ```javascript
 const electron = require('electron');
diff --git a/docs/api/web-contents.md b/docs/api/web-contents.md
index 0eee6c5bf8..e49e220dbb 100644
--- a/docs/api/web-contents.md
+++ b/docs/api/web-contents.md
@@ -1,8 +1,9 @@
 # webContents
 
+Render and control web pages using lifecycle events.
+
 `webContents` is an
 [EventEmitter](http://nodejs.org/api/events.html#events_class_events_eventemitter).
-
 It is responsible for rendering and controlling a web page and is a property of
 the [`BrowserWindow`](browser-window.md) object. An example of accessing the
 `webContents` object:
diff --git a/docs/api/web-frame.md b/docs/api/web-frame.md
index d9e02ac097..109bfa103d 100644
--- a/docs/api/web-frame.md
+++ b/docs/api/web-frame.md
@@ -1,7 +1,6 @@
 # webFrame
 
-The `web-frame` module allows you to customize the rendering of the current
-web page.
+Customize the rendering of the current web page.
 
 An example of zooming current page to 200%.
 
diff --git a/docs/api/web-view-tag.md b/docs/api/web-view-tag.md
index 214f93dbad..36b0513e55 100644
--- a/docs/api/web-view-tag.md
+++ b/docs/api/web-view-tag.md
@@ -1,5 +1,7 @@
 # The `<webview>` tag
 
+Display external web content in an isolated frame and process.
+
 Use the `webview` tag to embed 'guest' content (such as web pages) in your
 Electron app. The guest content is contained within the `webview` container.
 An embedded page within your app controls how the guest content is laid out and
diff --git a/docs/api/window-open.md b/docs/api/window-open.md
index 46e7432774..14a0dce65f 100644
--- a/docs/api/window-open.md
+++ b/docs/api/window-open.md
@@ -1,5 +1,7 @@
 # The `window.open` function
 
+Create a new window in a web page.
+
 When `window.open` is called to create a new window in a web page, a new instance
 of `BrowserWindow` will be created for the `url` and a proxy will be returned
 to `window.open` to let the page have limited control over it.

From 0527b17e4203f6593cdf64daa146b9a326039446 Mon Sep 17 00:00:00 2001
From: Zeke Sikelianos <zeke@sikelianos.com>
Date: Thu, 21 Apr 2016 15:39:12 -0700
Subject: [PATCH 2/4] blockquote summaries

---
 docs/api/accelerator.md                  | 2 +-
 docs/api/app.md                          | 2 +-
 docs/api/auto-updater.md                 | 2 +-
 docs/api/browser-window.md               | 2 +-
 docs/api/chrome-command-line-switches.md | 2 +-
 docs/api/clipboard.md                    | 2 +-
 docs/api/content-tracing.md              | 2 +-
 docs/api/crash-reporter.md               | 2 +-
 docs/api/desktop-capturer.md             | 2 +-
 docs/api/dialog.md                       | 2 +-
 docs/api/download-item.md                | 2 +-
 docs/api/environment-variables.md        | 2 +-
 docs/api/file-object.md                  | 2 +-
 docs/api/global-shortcut.md              | 2 +-
 docs/api/ipc-main.md                     | 2 +-
 docs/api/ipc-renderer.md                 | 2 +-
 docs/api/menu-item.md                    | 2 +-
 docs/api/menu.md                         | 2 +-
 docs/api/native-image.md                 | 2 +-
 docs/api/power-monitor.md                | 2 +-
 docs/api/power-save-blocker.md           | 2 +-
 docs/api/process.md                      | 2 +-
 docs/api/protocol.md                     | 2 +-
 docs/api/remote.md                       | 2 +-
 docs/api/session.md                      | 2 +-
 docs/api/shell.md                        | 2 +-
 docs/api/synopsis.md                     | 2 +-
 docs/api/tray.md                         | 2 +-
 docs/api/web-contents.md                 | 2 +-
 docs/api/web-frame.md                    | 2 +-
 docs/api/web-view-tag.md                 | 2 +-
 docs/api/window-open.md                  | 2 +-
 32 files changed, 32 insertions(+), 32 deletions(-)

diff --git a/docs/api/accelerator.md b/docs/api/accelerator.md
index ff2b8190a9..cf28e01037 100644
--- a/docs/api/accelerator.md
+++ b/docs/api/accelerator.md
@@ -1,6 +1,6 @@
 # Accelerator
 
-Define keyboard shortcuts.
+> Define keyboard shortcuts.
 
 Accelerators can contain multiple modifiers and key codes, combined by
 the `+` character.
diff --git a/docs/api/app.md b/docs/api/app.md
index b06f8e6b6a..8a2cdcfd92 100644
--- a/docs/api/app.md
+++ b/docs/api/app.md
@@ -1,6 +1,6 @@
 # app
 
-Control your application's event lifecycle.
+> Control your application's event lifecycle.
 
 The following example shows how to quit the application when the last window is
 closed:
diff --git a/docs/api/auto-updater.md b/docs/api/auto-updater.md
index daea501210..8ad3f8f16e 100644
--- a/docs/api/auto-updater.md
+++ b/docs/api/auto-updater.md
@@ -1,6 +1,6 @@
 # autoUpdater
 
-Enable apps to update themselves automatically.
+> Enable apps to update themselves automatically.
 
 The `autoUpdater` module provides and interface for the [Squirrel](https://github.com/Squirrel) framework.
 
diff --git a/docs/api/browser-window.md b/docs/api/browser-window.md
index b7536249f8..7289057b40 100644
--- a/docs/api/browser-window.md
+++ b/docs/api/browser-window.md
@@ -1,6 +1,6 @@
 # BrowserWindow
 
-Create and control browser windows.
+> Create and control browser windows.
 
 ```javascript
 // In the main process.
diff --git a/docs/api/chrome-command-line-switches.md b/docs/api/chrome-command-line-switches.md
index f7515a5f1f..71a5ce6a40 100644
--- a/docs/api/chrome-command-line-switches.md
+++ b/docs/api/chrome-command-line-switches.md
@@ -1,6 +1,6 @@
 # Supported Chrome command line switches
 
-Command line switches supported by Electron.
+> Command line switches supported by Electron.
 
 You can use [app.commandLine.appendSwitch][append-switch] to append them in
 your app's main script before the [ready][ready] event of [app][app] module is
diff --git a/docs/api/clipboard.md b/docs/api/clipboard.md
index 2f9440f80e..58e5a1c1b0 100644
--- a/docs/api/clipboard.md
+++ b/docs/api/clipboard.md
@@ -1,6 +1,6 @@
 # clipboard
 
-Perform copy and paste operations on the system clipboard.
+> Perform copy and paste operations on the system clipboard.
 
 The following example shows how to write a string to the clipboard:
 
diff --git a/docs/api/content-tracing.md b/docs/api/content-tracing.md
index 66c7679dd0..c69031850a 100644
--- a/docs/api/content-tracing.md
+++ b/docs/api/content-tracing.md
@@ -1,6 +1,6 @@
 # contentTracing
 
-Debug your application using Chromium's content module.
+> Debug your application using Chromium's content module.
 
 This module does not include a web interface
 so you need to open `chrome://tracing/` in a Chrome browser and load the
diff --git a/docs/api/crash-reporter.md b/docs/api/crash-reporter.md
index 0ef2317db6..1f8229eaa7 100644
--- a/docs/api/crash-reporter.md
+++ b/docs/api/crash-reporter.md
@@ -1,6 +1,6 @@
 # crashReporter
 
-Submit crash reports to a remote server.
+> Submit crash reports to a remote server.
 
 The following is an example of automatically submitting a crash report to a
 remote server:
diff --git a/docs/api/desktop-capturer.md b/docs/api/desktop-capturer.md
index c80928017a..505dd9596a 100644
--- a/docs/api/desktop-capturer.md
+++ b/docs/api/desktop-capturer.md
@@ -1,6 +1,6 @@
 # desktopCapturer
 
-Capture audio, video, and images from a microphone, camera, or
+> Capture audio, video, and images from a microphone, camera, or
 screen using the `getUserMedia` API.
 
 ```javascript
diff --git a/docs/api/dialog.md b/docs/api/dialog.md
index e052f10dca..a5f61a53e3 100644
--- a/docs/api/dialog.md
+++ b/docs/api/dialog.md
@@ -1,6 +1,6 @@
 # dialog
 
-Display native system dialogs for opening and saving files, alerting, etc.
+> Display native system dialogs for opening and saving files, alerting, etc.
 
 An example of showing a dialog to select multiple files and directories:
 
diff --git a/docs/api/download-item.md b/docs/api/download-item.md
index 02e5b39500..0f38ceedac 100644
--- a/docs/api/download-item.md
+++ b/docs/api/download-item.md
@@ -1,6 +1,6 @@
 # DownloadItem
 
-Trigger file downloads from remote sources.
+> Trigger file downloads from remote sources.
 
 `DownloadItem` is an EventEmitter represents a download item in Electron. It
 is used in `will-download` event of `Session` module, and allows users to
diff --git a/docs/api/environment-variables.md b/docs/api/environment-variables.md
index 6186c06904..7339661b09 100644
--- a/docs/api/environment-variables.md
+++ b/docs/api/environment-variables.md
@@ -1,6 +1,6 @@
 # Environment variables
 
-Control application configuration and behavior without changing code.
+> Control application configuration and behavior without changing code.
 
 Some behaviors of Electron are controlled by environment variables, because they
 are initialized earlier than command line and the app's code.
diff --git a/docs/api/file-object.md b/docs/api/file-object.md
index f1d3680eb8..31c6feddb5 100644
--- a/docs/api/file-object.md
+++ b/docs/api/file-object.md
@@ -1,6 +1,6 @@
 # `File` object
 
-Use the HTML5 `File` API to work natively with files on the filesystem.
+> Use the HTML5 `File` API to work natively with files on the filesystem.
 
 The DOM's File interface provides abstraction around native files in order to
 let users work on native files directly with the HTML5 file API. Electron has
diff --git a/docs/api/global-shortcut.md b/docs/api/global-shortcut.md
index c1bce458c8..08453d68a4 100644
--- a/docs/api/global-shortcut.md
+++ b/docs/api/global-shortcut.md
@@ -1,6 +1,6 @@
 # globalShortcut
 
-Detect keyboard events when the application does not have keyboard focus.
+> Detect keyboard events when the application does not have keyboard focus.
 
 The `globalShortcut` module can register/unregister a global keyboard shortcut
 with the operating system so that you can customize the operations for various
diff --git a/docs/api/ipc-main.md b/docs/api/ipc-main.md
index 1ddb0bb1c9..c8ba60ba31 100644
--- a/docs/api/ipc-main.md
+++ b/docs/api/ipc-main.md
@@ -1,6 +1,6 @@
 # ipcMain
 
-Communicate asynchronously from the main process to renderer processes.
+> Communicate asynchronously from the main process to renderer processes.
 
 The `ipcMain` module is an instance of the
 [EventEmitter](https://nodejs.org/api/events.html) class. When used in the main
diff --git a/docs/api/ipc-renderer.md b/docs/api/ipc-renderer.md
index 8d18524d1c..9835e42b46 100644
--- a/docs/api/ipc-renderer.md
+++ b/docs/api/ipc-renderer.md
@@ -1,6 +1,6 @@
 # ipcRenderer
 
-Communicate asynchronously from a renderer process to the main process.
+> Communicate asynchronously from a renderer process to the main process.
 
 The `ipcRenderer` module is an instance of the
 [EventEmitter](https://nodejs.org/api/events.html) class. It provides a few
diff --git a/docs/api/menu-item.md b/docs/api/menu-item.md
index 5c5532289a..0b5db94311 100644
--- a/docs/api/menu-item.md
+++ b/docs/api/menu-item.md
@@ -1,6 +1,6 @@
 # MenuItem
 
-Add items to application and context menus.
+> Add items to application and context menus.
 
 See [`menu`](menu.md) for examples.
 
diff --git a/docs/api/menu.md b/docs/api/menu.md
index 6ac8a9ea1e..4106dfdd40 100644
--- a/docs/api/menu.md
+++ b/docs/api/menu.md
@@ -1,6 +1,6 @@
 # Menu
 
-Create native application menus and context menus.
+> Create native application menus and context menus.
 
 This module is a main process module which can be used in a render process via
 the `remote` module.
diff --git a/docs/api/native-image.md b/docs/api/native-image.md
index ed3bbdacc9..1cbfcf4101 100644
--- a/docs/api/native-image.md
+++ b/docs/api/native-image.md
@@ -1,6 +1,6 @@
 # nativeImage
 
-Create tray, dock, and application icons using PNG or JPG files.
+> Create tray, dock, and application icons using PNG or JPG files.
 
 In Electron, for the APIs that take images, you can pass either file paths or
 `nativeImage` instances. An empty image will be used when `null` is passed.
diff --git a/docs/api/power-monitor.md b/docs/api/power-monitor.md
index 72cfbca1f1..75546dc801 100644
--- a/docs/api/power-monitor.md
+++ b/docs/api/power-monitor.md
@@ -1,6 +1,6 @@
 # powerMonitor
 
-Monitor power state changes.
+> Monitor power state changes.
 
 You can only use it in the main process. You should not use this module until the `ready`
 event of the `app` module is emitted.
diff --git a/docs/api/power-save-blocker.md b/docs/api/power-save-blocker.md
index 315bbdb9be..3ec0733864 100644
--- a/docs/api/power-save-blocker.md
+++ b/docs/api/power-save-blocker.md
@@ -1,6 +1,6 @@
 # powerSaveBlocker
 
-Block the system from entering low-power (sleep) mode.
+> Block the system from entering low-power (sleep) mode.
 
 For example:
 
diff --git a/docs/api/process.md b/docs/api/process.md
index 1805337095..80f0e539d8 100644
--- a/docs/api/process.md
+++ b/docs/api/process.md
@@ -1,6 +1,6 @@
 # process
 
-Get information about the running application process.
+> Get information about the running application process.
 
 The `process` object in Electron has the following differences from the one in
 upstream node:
diff --git a/docs/api/protocol.md b/docs/api/protocol.md
index ade04c1cc3..b3062bb632 100644
--- a/docs/api/protocol.md
+++ b/docs/api/protocol.md
@@ -1,6 +1,6 @@
 # protocol
 
-Register a custom protocol to intercept click events from other running
+> Register a custom protocol to intercept click events from other running
 applications.
 
 An example of implementing a protocol that has the same effect as the
diff --git a/docs/api/remote.md b/docs/api/remote.md
index fb585a0fc3..65f58f01b0 100644
--- a/docs/api/remote.md
+++ b/docs/api/remote.md
@@ -1,6 +1,6 @@
 # remote
 
-Communicate between the renderer process and the main process.
+> Communicate between the renderer process and the main process.
 
 The `remote` module provides a simple way to do inter-process communication
 (IPC) between the renderer process (web page) and the main process.
diff --git a/docs/api/session.md b/docs/api/session.md
index e7689c8e4b..390a9a5e4d 100644
--- a/docs/api/session.md
+++ b/docs/api/session.md
@@ -1,6 +1,6 @@
 # session
 
-Manage browser cookies, cache, and other session data.
+> Manage browser cookies, cache, and other session data.
 
 The `session` module can be used to create new `Session` objects.
 
diff --git a/docs/api/shell.md b/docs/api/shell.md
index b340acaebf..8ede115f7c 100644
--- a/docs/api/shell.md
+++ b/docs/api/shell.md
@@ -1,6 +1,6 @@
 # shell
 
-Manage files and URLs using their default applications.
+> Manage files and URLs using their default applications.
 
 The `shell` module provides functions related to desktop integration.
 
diff --git a/docs/api/synopsis.md b/docs/api/synopsis.md
index d79942531e..641df7e260 100644
--- a/docs/api/synopsis.md
+++ b/docs/api/synopsis.md
@@ -1,6 +1,6 @@
 # Synopsis
 
-Info about Node.js and the main and renderer processes.
+> Info about Node.js and the main and renderer processes.
 
 All of [Node.js's built-in modules](http://nodejs.org/api/) are available in
 Electron and third-party node modules also fully supported as well (including
diff --git a/docs/api/tray.md b/docs/api/tray.md
index d6bf2b3c73..1ea0859f14 100644
--- a/docs/api/tray.md
+++ b/docs/api/tray.md
@@ -1,6 +1,6 @@
 # Tray
 
-Add icons and context menus to the system's notification area.
+> Add icons and context menus to the system's notification area.
 
 ```javascript
 const electron = require('electron');
diff --git a/docs/api/web-contents.md b/docs/api/web-contents.md
index e49e220dbb..5c0f457538 100644
--- a/docs/api/web-contents.md
+++ b/docs/api/web-contents.md
@@ -1,6 +1,6 @@
 # webContents
 
-Render and control web pages using lifecycle events.
+> Render and control web pages using lifecycle events.
 
 `webContents` is an
 [EventEmitter](http://nodejs.org/api/events.html#events_class_events_eventemitter).
diff --git a/docs/api/web-frame.md b/docs/api/web-frame.md
index 109bfa103d..b2d8aa0f41 100644
--- a/docs/api/web-frame.md
+++ b/docs/api/web-frame.md
@@ -1,6 +1,6 @@
 # webFrame
 
-Customize the rendering of the current web page.
+> Customize the rendering of the current web page.
 
 An example of zooming current page to 200%.
 
diff --git a/docs/api/web-view-tag.md b/docs/api/web-view-tag.md
index 36b0513e55..5f4a422a13 100644
--- a/docs/api/web-view-tag.md
+++ b/docs/api/web-view-tag.md
@@ -1,6 +1,6 @@
 # The `<webview>` tag
 
-Display external web content in an isolated frame and process.
+> Display external web content in an isolated frame and process.
 
 Use the `webview` tag to embed 'guest' content (such as web pages) in your
 Electron app. The guest content is contained within the `webview` container.
diff --git a/docs/api/window-open.md b/docs/api/window-open.md
index 14a0dce65f..b4f5057dae 100644
--- a/docs/api/window-open.md
+++ b/docs/api/window-open.md
@@ -1,6 +1,6 @@
 # The `window.open` function
 
-Create a new window in a web page.
+> Create a new window in a web page.
 
 When `window.open` is called to create a new window in a web page, a new instance
 of `BrowserWindow` will be created for the `url` and a proxy will be returned

From 2c8261b4292413b926f2d31da6cad39c4baf486d Mon Sep 17 00:00:00 2001
From: Zeke Sikelianos <zeke@sikelianos.com>
Date: Fri, 22 Apr 2016 10:30:49 -0700
Subject: [PATCH 3/4] update excerpts based on feedback

---
 docs/api/content-tracing.md  | 3 ++-
 docs/api/desktop-capturer.md | 4 ++--
 docs/api/download-item.md    | 6 +++---
 docs/api/protocol.md         | 3 +--
 docs/api/remote.md           | 2 +-
 docs/api/session.md          | 2 +-
 docs/api/synopsis.md         | 2 +-
 docs/api/web-contents.md     | 2 +-
 8 files changed, 12 insertions(+), 12 deletions(-)

diff --git a/docs/api/content-tracing.md b/docs/api/content-tracing.md
index c69031850a..85036c0d70 100644
--- a/docs/api/content-tracing.md
+++ b/docs/api/content-tracing.md
@@ -1,6 +1,7 @@
 # contentTracing
 
-> Debug your application using Chromium's content module.
+> Collect tracing data from Chromium's content module for finding performance
+bottlenecks and slow operations.
 
 This module does not include a web interface
 so you need to open `chrome://tracing/` in a Chrome browser and load the
diff --git a/docs/api/desktop-capturer.md b/docs/api/desktop-capturer.md
index 505dd9596a..dc523c3a42 100644
--- a/docs/api/desktop-capturer.md
+++ b/docs/api/desktop-capturer.md
@@ -1,7 +1,7 @@
 # desktopCapturer
 
-> Capture audio, video, and images from a microphone, camera, or
-screen using the `getUserMedia` API.
+> List `getUserMedia` sources for capturing audio, video, and images from a
+microphone, camera, or screen.
 
 ```javascript
 // In the renderer process.
diff --git a/docs/api/download-item.md b/docs/api/download-item.md
index 0f38ceedac..4418f61c19 100644
--- a/docs/api/download-item.md
+++ b/docs/api/download-item.md
@@ -1,9 +1,9 @@
 # DownloadItem
 
-> Trigger file downloads from remote sources.
+> Control file downloads from remote sources.
 
-`DownloadItem` is an EventEmitter represents a download item in Electron. It
-is used in `will-download` event of `Session` module, and allows users to
+`DownloadItem` is an EventEmitter that 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
diff --git a/docs/api/protocol.md b/docs/api/protocol.md
index b3062bb632..fe7dfabc64 100644
--- a/docs/api/protocol.md
+++ b/docs/api/protocol.md
@@ -1,7 +1,6 @@
 # protocol
 
-> Register a custom protocol to intercept click events from other running
-applications.
+> Register a custom protocol and intercept existing protocols.
 
 An example of implementing a protocol that has the same effect as the
 `file://` protocol:
diff --git a/docs/api/remote.md b/docs/api/remote.md
index 65f58f01b0..454758c913 100644
--- a/docs/api/remote.md
+++ b/docs/api/remote.md
@@ -1,6 +1,6 @@
 # remote
 
-> Communicate between the renderer process and the main process.
+> Use main process modules from the renderer process.
 
 The `remote` module provides a simple way to do inter-process communication
 (IPC) between the renderer process (web page) and the main process.
diff --git a/docs/api/session.md b/docs/api/session.md
index 390a9a5e4d..5bc819fb2b 100644
--- a/docs/api/session.md
+++ b/docs/api/session.md
@@ -1,6 +1,6 @@
 # session
 
-> Manage browser cookies, cache, and other session data.
+> Manage browser sessions, cookies, cache, proxy settings, etc.
 
 The `session` module can be used to create new `Session` objects.
 
diff --git a/docs/api/synopsis.md b/docs/api/synopsis.md
index 641df7e260..a2aa58f57f 100644
--- a/docs/api/synopsis.md
+++ b/docs/api/synopsis.md
@@ -1,6 +1,6 @@
 # Synopsis
 
-> Info about Node.js and the main and renderer processes.
+> How to use Node.js and Electron APIs.
 
 All of [Node.js's built-in modules](http://nodejs.org/api/) are available in
 Electron and third-party node modules also fully supported as well (including
diff --git a/docs/api/web-contents.md b/docs/api/web-contents.md
index 5c0f457538..64e7cea60e 100644
--- a/docs/api/web-contents.md
+++ b/docs/api/web-contents.md
@@ -1,6 +1,6 @@
 # webContents
 
-> Render and control web pages using lifecycle events.
+> Render and control web pages.
 
 `webContents` is an
 [EventEmitter](http://nodejs.org/api/events.html#events_class_events_eventemitter).

From 799fd13c503c52deb095dfd234c88825a5ecab55 Mon Sep 17 00:00:00 2001
From: Zeke Sikelianos <zeke@sikelianos.com>
Date: Fri, 22 Apr 2016 11:42:54 -0700
Subject: [PATCH 4/4] more updates to api summaries based on feedback

---
 docs/api/auto-updater.md                 | 4 ++--
 docs/api/chrome-command-line-switches.md | 4 ++--
 docs/api/content-tracing.md              | 6 +++---
 docs/api/menu-item.md                    | 2 +-
 docs/api/protocol.md                     | 2 +-
 docs/api/window-open.md                  | 2 +-
 6 files changed, 10 insertions(+), 10 deletions(-)

diff --git a/docs/api/auto-updater.md b/docs/api/auto-updater.md
index 8ad3f8f16e..211d0c69a5 100644
--- a/docs/api/auto-updater.md
+++ b/docs/api/auto-updater.md
@@ -1,8 +1,8 @@
 # autoUpdater
 
-> Enable apps to update themselves automatically.
+> Enable apps to automatically update themselves.
 
-The `autoUpdater` module provides and interface for the [Squirrel](https://github.com/Squirrel) framework.
+The `autoUpdater` module provides an interface for the [Squirrel](https://github.com/Squirrel) framework.
 
 You can quickly launch a multi-platform release server for distributing your
 application by using one of these projects:
diff --git a/docs/api/chrome-command-line-switches.md b/docs/api/chrome-command-line-switches.md
index 71a5ce6a40..17059435ea 100644
--- a/docs/api/chrome-command-line-switches.md
+++ b/docs/api/chrome-command-line-switches.md
@@ -3,8 +3,8 @@
 > Command line switches supported by Electron.
 
 You can use [app.commandLine.appendSwitch][append-switch] to append them in
-your app's main script before the [ready][ready] event of [app][app] module is
-emitted:
+your app's main script before the [ready][ready] event of the [app][app] module
+is emitted:
 
 ```javascript
 const app = require('electron').app;
diff --git a/docs/api/content-tracing.md b/docs/api/content-tracing.md
index 85036c0d70..a9414d3487 100644
--- a/docs/api/content-tracing.md
+++ b/docs/api/content-tracing.md
@@ -3,9 +3,9 @@
 > Collect tracing data from Chromium's content module for finding performance
 bottlenecks and slow operations.
 
-This module does not include a web interface
-so you need to open `chrome://tracing/` in a Chrome browser and load the
-generated file to view the result.
+This module does not include a web interface so you need to open
+`chrome://tracing/` in a Chrome browser and load the generated file to view the
+result.
 
 ```javascript
 const contentTracing = require('electron').contentTracing;
diff --git a/docs/api/menu-item.md b/docs/api/menu-item.md
index 0b5db94311..b67032271e 100644
--- a/docs/api/menu-item.md
+++ b/docs/api/menu-item.md
@@ -1,6 +1,6 @@
 # MenuItem
 
-> Add items to application and context menus.
+> Add items to native application menus and context menus.
 
 See [`menu`](menu.md) for examples.
 
diff --git a/docs/api/protocol.md b/docs/api/protocol.md
index fe7dfabc64..aa9b43486d 100644
--- a/docs/api/protocol.md
+++ b/docs/api/protocol.md
@@ -1,6 +1,6 @@
 # protocol
 
-> Register a custom protocol and intercept existing protocols.
+> Register a custom protocol and intercept existing protocol requests.
 
 An example of implementing a protocol that has the same effect as the
 `file://` protocol:
diff --git a/docs/api/window-open.md b/docs/api/window-open.md
index b4f5057dae..abb0760f12 100644
--- a/docs/api/window-open.md
+++ b/docs/api/window-open.md
@@ -1,6 +1,6 @@
 # The `window.open` function
 
-> Create a new window in a web page.
+> Open a new window and load a URL.
 
 When `window.open` is called to create a new window in a web page, a new instance
 of `BrowserWindow` will be created for the `url` and a proxy will be returned