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] 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 83d8d3a7c2de..ff2b8190a942 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 54e40263eab9..b06f8e6b6afb 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 dccae1212aa0..daea50121001 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 c24972815266..b7536249f8f6 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 8e8aa38e62dc..f7515a5f1fbb 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 7f95a1af26d2..2f9440f80e99 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 0b83c2759c67..66c7679dd090 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 9b7141e364e9..0ef2317db6bd 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 b39a09e5aa8b..c80928017ace 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 3eb0292a4937..e052f10dca96 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 f117ffc57a78..02e5b3950041 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 3483c19d6431..6186c06904a7 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 01d49c39155f..f1d3680eb8a8 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 8e1dd46ec56e..12497db4dae9 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 f20758406b7c..c1bce458c893 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 84fbcfd5a72f..1ddb0bb1c991 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 46a2331af43b..8d18524d1cd8 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 1b36432ab297..5c5532289a96 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 cb5a0cbe2df8..6ac8a9ea1e00 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 e0c3ae466248..ed3bbdacc9ab 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 4465b253a754..72cfbca1f13e 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 a3ef798411f2..315bbdb9bec4 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 17c0be10926c..180533709532 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 e57a34ef89b5..ade04c1cc308 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 7bdbe0362f60..fb585a0fc3d5 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 90ef183a8a8d..5f8188f0d8a6 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 900301803632..e7689c8e4b78 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 823dc481bb07..b340acaebf6c 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 466b13828c41..d79942531e3c 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 aa972c57cd92..d6bf2b3c73e5 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 0eee6c5bf8bb..e49e220dbbd0 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 d9e02ac097e7..109bfa103d59 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 214f93dbad6f..36b0513e556e 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 46e74327741f..14a0dce65f25 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.