Merge pull request #2604 from atom/jl-std-docs-4

Standardize: global-shortcuts, ipc (main), ipc (render)

docs/api/global-shortcut.md

@@ -1,9 +1,12 @@
 # global-shortcut
 
 The `global-shortcut` module can register/unregister a global keyboard shortcut
-with the operating system, so that you can customize the operations for various shortcuts.
-Note that the shortcut is global; it will work even if the app does not have the keyboard focus.
-You should not use this module until the `ready` event of the app module is emitted.
+with the operating system so that you can customize the operations for various
+shortcuts.
+
+**Note**: The shortcut is global; it will work even if the app does
+not have the keyboard focus. You should not use this module until the `ready`
+event of the app module is emitted.
 
 ```javascript
 var app = require('app');
@@ -32,7 +35,11 @@ app.on('will-quit', function() {
 });
 ```
 
-## globalShortcut.register(accelerator, callback)
+## Methods
+
+The `global-shortcut` module has the following methods:
+
+### `globalShortcut.register(accelerator, callback)`
 
 * `accelerator` [Accelerator](accelerator.md)
 * `callback` Function
@@ -40,18 +47,19 @@ app.on('will-quit', function() {
 Registers a global shortcut of `accelerator`. The `callback` is called when
 the registered shortcut is pressed by the user.
 
-## globalShortcut.isRegistered(accelerator)
+### `globalShortcut.isRegistered(accelerator)`
 
 * `accelerator` [Accelerator](accelerator.md)
 
-Returns `true` or `false` depending on whether the shortcut `accelerator` is registered.
+Returns `true` or `false` depending on whether the shortcut `accelerator` is
+registered.
 
-## globalShortcut.unregister(accelerator)
+### `globalShortcut.unregister(accelerator)`
 
 * `accelerator` [Accelerator](accelerator.md)
 
-Unregisters the global shortcut of `keycode`.
+Unregisters the global shortcut of `accelerator`.
 
-## globalShortcut.unregisterAll()
+### `globalShortcut.unregisterAll()`
 
 Unregisters all the global shortcuts.

docs/api/ipc-main-process.md

@@ -1,17 +1,22 @@
 # ipc (main process)
 
-Handles asynchronous and synchronous message sent from a renderer process (web
-page).
+The `ipc` module, when used in the main process, handles asynchronous and
+synchronous messages sent from a renderer process (web page). Messages sent from
+a renderer will be emitted to this module.
 
-The messages sent from a renderer would be emitted to this module, the event name
-is the `channel` when sending message. To reply a synchronous message, you need
-to set `event.returnValue`, to send an asynchronous back to the sender, you can
-use `event.sender.send(...)`.
+## Sending Messages
 
-It's also possible to send messages from main process to the renderer process,
-see [WebContents.send](browser-window.md#webcontentssendchannel-args) for more.
+It is also possible to send messages from the main process to the renderer
+process, see [WebContents.send](browser-window.md#webcontentssendchannel-args)
+for more information.
 
-An example of sending and handling messages:
+- When sending a message, the event name is the `channel`.
+- To reply a synchronous message, you need to set `event.returnValue`.
+- To send an asynchronous back to the sender, you can use
+  `event.sender.send(...)`.
+
+An example of sending and handling messages between the render and main
+processes:
 
 ```javascript
 // In main process.
@@ -38,12 +43,34 @@ ipc.on('asynchronous-reply', function(arg) {
 ipc.send('asynchronous-message', 'ping');
 ```
 
-## Class: Event
+## Listening for Messages
 
-### Event.returnValue
+The `ipc` module has the following method to listen for events:
 
-Assign to this to return an value to synchronous messages.
+### `ipc.on(channel, callback)`
 
-### Event.sender
+* `channel` String - The event name.
+* `callback` Function
 
-The `WebContents` that sent the message.
+When the event occurs the `callback` is called with an `event` object and a
+message, `arg`.
+
+## IPC Events
+
+The `event` object passed to the `callback` has the following methods:
+
+### `Event.returnValue`
+
+Set this to the value to be returned in a synchronous message.
+
+### `Event.sender`
+
+Returns the `WebContents` that sent the message.
+
+### `Event.sender.send(channel[, arg1][, arg2][, ...])`
+
+* `channel` String - The event name.
+* `arg` (optional)
+
+This sends an asynchronous message back to the render process. Optionally, there
+can be one or a series of arguments, `arg`, which can have any type.

docs/api/ipc-renderer.md

@@ -1,29 +1,52 @@
 # ipc (renderer)
 
 The `ipc` module provides a few methods so you can send synchronous and
-asynchronous messages to the main process, and also receive messages sent from
-main process. If you want to make use of modules of main process from renderer
+asynchronous messages from the render process (web page) to the main process.
+You can also receive replies from the main process.
+
+**Note**: If you want to make use of modules in the main process from the renderer
 process, you might consider using the [remote](remote.md) module.
 
-See [ipc (main process)](ipc-main-process.md) for examples.
+See [ipc (main process)](ipc-main-process.md) for code examples.
 
-## ipc.send(channel[, args...])
+## Methods
 
-Send `args..` to the renderer via `channel` in asynchronous message, the main
-process can handle it by listening to the `channel` event of `ipc` module.
+The `ipc` module has the following methods for sending messages:
 
-## ipc.sendSync(channel[, args...])
+**Note**: When using these methods to send a `message` you must also listen
+for it in the main process with [`ipc (main process)`](ipc-main-process.md).
 
-Send `args..` to the renderer via `channel` in synchronous message, and returns
-the result sent from main process. The main process can handle it by listening to
-the `channel` event of `ipc` module, and returns by setting `event.returnValue`.
+### `ipc.send(channel[, arg1][, arg2][, ...])`
 
-**Note:** Usually developers should never use this API, since sending
-synchronous message would block the whole renderer process.
+* `channel` String - The event name.
+* `arg` (optional)
 
-## ipc.sendToHost(channel[, args...])
+Send an event to the main process asynchronously via a `channel`. Optionally,
+there can be a message: one or a series of arguments, `arg`, which can have any
+type. The main process handles it by listening for the `channel` event with
+`ipc`.
 
-Like `ipc.send` but the message will be sent to the host page instead of the
-main process.
+### `ipc.sendSync(channel[, arg1][, arg2][, ...])`
 
-This is mainly used by the page in `<webview>` to communicate with host page.
+* `channel` String - The event name.
+* `arg` (optional)
+
+Send an event to the main process synchronously via a `channel`. Optionally,
+there can be a message: one or a series of arguments, `arg`, which can have any
+type. The main process handles it by listening for the `channel` event with
+`ipc`.
+
+The main process handles it by listening for the `channel` event with `ipc` and
+replies by setting the `event.returnValue`.
+
+**Note:** Sending a synchronous message will block the whole renderer process so
+using this method is not recommended.
+
+### `ipc.sendToHost(channel[, arg1][, arg2][, ...])`
+
+* `channel` String - The event name.
+* `arg` (optional)
+
+Like `ipc.send` but the event will be sent to the host page in a `<webview>`
+instead of the main process. Optionally, there can be a message: one or a series
+of arguments, `arg`, which can have any type.