Merge pull request #5249 from electron/api-summaries

create a one-liner description for each API

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:
 

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:

docs/api/auto-updater.md

@@ -1,6 +1,8 @@
 # autoUpdater
 
-This module provides an interface for the `Squirrel` auto-updater framework.
+> Enable apps to automatically update themselves.
+
+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:

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.

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 the [app][app] module
+is emitted:
 
 ```javascript
 const app = require('electron').app;

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

docs/api/content-tracing.md

@@ -1,9 +1,11 @@
 # 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
-so you need to open `chrome://tracing/` in a Chrome browser and load the
-generated file to view the result.
+> 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.
 
 ```javascript
 const contentTracing = require('electron').contentTracing;

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:

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`.
+> List `getUserMedia` sources for capturing audio, video, and images from a
+microphone, camera, or screen.
 
 ```javascript
 // In the renderer process.

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:
 

docs/api/download-item.md

@@ -1,7 +1,9 @@
 # DownloadItem
 
-`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 file downloads from remote sources.
+
+`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

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.
 

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

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

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.

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

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

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 native application menus and context menus.
 
 See [`menu`](menu.md) for examples.
 

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.
 

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.
 

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:

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:
 

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:
 

docs/api/protocol.md

@@ -1,7 +1,6 @@
 # protocol
 
-The `protocol` module can register a custom protocol or intercept an existing
-protocol.
+> Register a custom protocol and intercept existing protocol requests.
 
 An example of implementing a protocol that has the same effect as the
 `file://` protocol:

docs/api/remote.md

@@ -1,5 +1,7 @@
 # remote
 
+> 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.
 

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).
 

docs/api/session.md

@@ -1,5 +1,7 @@
 # session
 
+> Manage browser sessions, cookies, cache, proxy settings, etc.
+
 The `session` module can be used to create new `Session` objects.
 
 You can also access the `session` of existing pages by using the `session`

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:

docs/api/synopsis.md

@@ -1,5 +1,7 @@
 # Synopsis
 
+> 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
 the [native modules](../tutorial/using-native-node-modules.md)).

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');

docs/api/web-contents.md

@@ -1,8 +1,9 @@
 # webContents
 
+> Render and control web pages.
+
 `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:

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%.
 

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

docs/api/window-open.md

@@ -1,5 +1,7 @@
 # The `window.open` function
 
+> 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
 to `window.open` to let the page have limited control over it.