Merge pull request #285 from GregMefford/patch-3

Doc: grammar/content fixes in the remote module

docs/api/remote.md

@@ -1,14 +1,14 @@
 # remote
 
 The `remote` module provides a simple way to do inter-process communication
-between renderer process and browser process.
+between the renderer process and the browser process.
 
-In atom-shell, all GUI related modules are only available in the browser
-process, if users want to call an browser side API in the renderer process
-, they usually would have to explicitly send inter-process messages to the
-browser process. But with the `remote` module, users can invoke methods of
-objects living in browser process without sending inter-process messages
-directly, like Java's
+In atom-shell, only GUI-related modules are available in the renderer process.
+Without the `remote` module, users who wanted to call a browser-side API in
+the renderer process would have to explicitly send inter-process messages
+to the browser process. With the `remote` module, users can invoke methods of
+browser-side object without explicitly sending inter-process messages,
+similar to Java's
 [RMI](http://en.wikipedia.org/wiki/Java_remote_method_invocation).
 
 An example of creating a browser window in renderer process:
@@ -22,47 +22,46 @@ win.loadUrl('https://github.com');
 
 ## Remote objects
 
-Each object (including function) returned by `remote` module represents an
-object in browser process (we call it remote object or remote function), when
-you invoke methods of a remote object, or call a remote function, or even create
+Each object (including functions) returned by the `remote` module represents an
+object in the browser process (we call it a remote object or remote function).
+When you invoke methods of a remote object, call a remote function, or create
 a new object with the remote constructor (function), you are actually sending
 synchronous inter-process messages.
 
-In the example above, both `BrowserWindow` and `win` were remote objects. And
-`new BrowserWindow` didn't create a `BrowserWindow` object in renderer process,
-instead it created a `BrowserWindow` object in browser process, and returned the
-corresponding remote object in renderer process, namely the `win` object.
+In the example above, both `BrowserWindow` and `win` were remote objects and
+`new BrowserWindow` didn't create a `BrowserWindow` object in the renderer process.
+Instead, it created a `BrowserWindow` object in the browser process and returned the
+corresponding remote object in the renderer process, namely the `win` object.
 
 ## Lifetime of remote objects
 
-Atom-shell makes sure that as long as the remote object in renderer process
+Atom-shell makes sure that as long as the remote object in the renderer process
 lives (in other words, has not been garbage collected), the corresponding object
-in browser process would never be released. And when the remote object has been
-garbage collected, the corresponding object in browser process would be
+in the browser process would never be released. When the remote object has been
+garbage collected, the corresponding object in the browser process would be
 dereferenced.
 
-But it also means that, if the remote object is leaked in renderer process, like
-being stored in a map but never got freed, the corresponding object in browser
-process would also be leaked too. So you should be very careful not to leak
-remote objects.
+If the remote object is leaked in renderer process (e.g. stored in a map but never
+freed), the corresponding object in the browser process would also be leaked,
+so you should be very careful not to leak remote objects.
 
 Primary value types like strings and numbers, however, are sent by copy.
 
 ## Passing callbacks to browser
 
-Some APIs in browser process accepts callbacks, and it would be attempting to
-pass callbacks when calling a remote function. Yes `remote` module does support
-doing this, but you should also be extremely careful on this.
+Some APIs in the browser process accept callbacks, and it would be attempting to
+pass callbacks when calling a remote function. The `remote` module does support
+doing this, but you should also be extremely careful with this.
 
-First, in order to avoid dead locks, the callbacks passed to browser process
-would be called asynchronously, so you should not expect the browser process to
+First, in order to avoid deadlocks, the callbacks passed to the browser process
+are called asynchronously, so you should not expect the browser process to
 get the return value of the passed callbacks.
 
-Second, the callbacks passed to browser process would not get released
-automatically after they were called, instead they would persistent until the
-browser process garbage collected them.
+Second, the callbacks passed to the browser process will not get released
+automatically after they are called. Instead, they will persistent until the
+browser process garbage-collects them.
 
-For example, following code seems innocent at first glance, It installed a
+For example, the following code seems innocent at first glance. It installs a
 callback for the `close` event on a remote object:
 
 ```javascript
@@ -72,28 +71,28 @@ remote.getCurrentWindow().on('close', function() {
 });
 ```
 
-But the callback would be stored in the browser process persistently until you
+The problem is that the callback would be stored in the browser process until you
 explicitly uninstall it! So each time you reload your window, the callback would
-be installed for once and previous callbacks were just leak. To make things
+be installed again and previous callbacks would just leak. To make things
 worse, since the context of previously installed callbacks have been released,
-when `close` event was emitted exceptions would happen in browser process.
+when the `close` event was emitted, exceptions would be raised in the browser process.
 
-So generally, unless you are clear what you are doing, you should always avoid
-passing callbacks to browser process.
+Generally, unless you are clear what you are doing, you should always avoid
+passing callbacks to the browser process.
 
 ## Remote buffer
 
-An instance of node's `Buffer` is an object, so when you got a `Buffer` from
-browser process, what you got was indeed a remote object (let's call it remote
+An instance of node's `Buffer` is an object, so when you get a `Buffer` from
+the browser process, what you get is indeed a remote object (let's call it remote
 buffer), and everything would just follow the rules of remote objects.
 
-However you should remember that though a remote buffer behaves like the real
+However you should remember that although a remote buffer behaves like the real
 `Buffer`, it's not a `Buffer` at all. If you pass a remote buffer to node APIs
-that accepting `Buffer`, you should assume the remote buffer would be treated
+that accept a `Buffer`, you should assume the remote buffer would be treated
 like a normal object, instead of a `Buffer`.
 
-For example you can call `BrowserWindow.capturePage` in renderer process, which
-returns a `Buffer` by calling passed callback:
+For example, you can call `BrowserWindow.capturePage` in the renderer process, which
+returns a `Buffer` by calling the passed callback:
 
 ```javascript
 var remote = require('remote');
@@ -106,12 +105,12 @@ remote.getCurrentWindow().capturePage(function(buf) {
 ```
 
 But you may be surprised to find that the file written was corrupted. This is
-because when you called `fs.writeFile`, you thought `buf` was a `Buffer`, but
-indeed it was a remote buffer, and it would be converted to string before it was
-written to file. Since `buf` contained binary data and could not be represented
-by UTF-8 encoded string, the written file would be corrupted.
+because when you called `fs.writeFile`, thinking that `buf` was a `Buffer` when
+in fact it was a remote buffer, and it was converted to string before it was
+written to the file. Since `buf` contained binary data and could not be represented
+by a UTF-8 encoded string, the written file was corrupted.
 
-The workaround is to write the `buf` in browser process, where it is a real
+The work-around is to write the `buf` in the browser process, where it is a real
 `Buffer`:
 
 ```javascript
@@ -125,8 +124,8 @@ remote.getCurrentWindow().capturePage(function(buf) {
 
 The same thing could happen for all native types, but usually it would just
 throw a type error. The `Buffer` deserves your special attention because it
-can be converted to string and APIs accepting `Buffer` usually accept string
-too, and data corruption only happens when it contains binary data.
+might be converted to string, and APIs accepting `Buffer` usually accept string
+too, and data corruption could happen when it contains binary data.
 
 ## remote.require(module)
 
@@ -137,7 +136,7 @@ Returns the object returned by `require(module)` in the browser process.
 ## remote.getCurrentWindow()
 
 Returns the [BrowserWindow](browser-window.md) object which
-represents current window.
+represents the current window.
 
 ## remote.getGlobal(name)
 
@@ -148,5 +147,5 @@ process.
 
 ## remote.process
 
-Returns the `process` object in the browser process, this is the same with
-`remote.getGlobal('process')` but gets cached.
+Returns the `process` object in the browser process. This is the same as
+`remote.getGlobal('process')`, but gets cached.