doc: Separate pages into sub directories.

docs/api/renderer/ipc-renderer.md

@@ -0,0 +1,79 @@
+# ipc (renderer)
+
+The `ipc` module provides a few methods so you can send synchronous and
+asynchronous messages to the browser, and also receive messages sent from
+browser. If you want to make use of modules of browser from renderer, you
+might consider using the [remote](remote.md) module.
+
+An example of echoing messages between browser and renderer:
+
+```javascript
+// In browser:
+var ipc = require('ipc');
+ipc.on('message', function(processId, routingId, m) {
+  ipc.send(processId, routingId, m);
+});
+```
+
+```javascript
+// In renderer:
+var ipc = require('ipc');
+ipc.on('message', function(m) {
+  console.log('Received message', m);
+});
+ipc.send('Hello world');
+```
+
+An example of sending synchronous message from renderer to browser:
+
+```javascript
+// In browser:
+var ipc = require('ipc');
+ipc.on('browser-data-request', function(event, processId, routingId, message) {
+  event.result = 'THIS SOME DATA FROM THE BROWSER';
+});
+```
+
+```javascript
+// In renderer:
+var ipc = require('ipc');
+console.log(ipc.sendChannelSync('browser-data-request', 'THIS IS FROM THE RENDERER'));
+```
+
+## Event: 'message'
+
+Emitted when browser sent a message to this window.
+
+## ipc.send([args...])
+
+Send all arguments to the browser and return immediately, the browser should
+handle the message by listening to the `message` event.
+
+## ipc.sendSync([args...])
+
+Send all arguments to the browser synchronously, and returns the result sent
+from browser. The browser should handle the message by listening to the
+`sync-message` event.
+
+**Note:** Usually developers should never use this API, since sending
+synchronous message would block the browser.
+
+## ipc.sendChannel(channel, [args...])
+
+* `channel` String
+
+This is the same with `ipc.send`, except that the browser should listen to the
+`channel` event. The `ipc.send(args...)` can be seen as
+`ipc.sendChannel('message', args...)`.
+
+
+## ipc.sendChannelSync(channel, [args...])
+
+* `channel` String
+
+This is the same with `ipc.sendSync`, except that the browser should listen to
+the `channel` event. The `ipc.sendSync(args...)` can be seen as
+`ipc.sendChannelSync('sync-message', args...)`.
+
+**Note:** Usually developers should never use this API, since sending
+synchronous message would block the browser.

docs/api/renderer/remote.md

@@ -0,0 +1,82 @@
+# remote
+
+It's common that the developers want to use modules in browsers from the
+renderer, like closing current window, opening file dialogs, etc. Instead of
+writing IPC code for every operation you want to do, atom-shell provides the
+`remote` module to let you do RPC call just like using normal javascript
+objects.
+
+An example of creating a window in renderer:
+
+```javascript
+var remote = require('remote');
+var BrowserWindow = remote.require('browser-window');
+var win = new BrowserWindow({ width: 800, height: 600 });
+win.loadUrl('https://github.com');
+```
+
+## Lifetime of remote objects
+
+Every object returned by `remote` module represents an object in browser (e.g.
+a remote object), so when you call methods of an object, or call a returned
+function, or even create a object with the returned constructor, you are
+indeed making a synchronous RPC call. And when the renderer releases the last
+reference to the remote object, the browser would release the corresponding
+reference too.
+
+This also means that, if the renderer keeps a reference to an object in
+browser, the object would never be released. So be careful to never leak the
+remote objects.
+
+## Passing callbacks
+
+Many APIs in browser accepts callbacks, so the `remote` module also supports
+passing callbacks when calling remote functions, and the callbacks passed
+would become remote functions in the browser.
+
+But in order to avoid possible dead locks, the callbacks passed to browser
+would be called asynchronously in browser, so you should never expect the
+browser to get the return value of the passed callback.
+
+Another thing is the lifetime of the remote callbacks in browser, it might be
+very tempting to do things like following:
+
+```javascript
+var remote = require('remote');
+remote.getCurrentWindow().on('close', function() {
+  // blabla...
+});
+```
+
+Yes it will work correctly, but when you reload the window, the callback you
+setup on the object in browser will not be erased, resources are leaked and
+there is no magic in javascript to release a referenced object.
+
+So if you really need to keep a reference of callbacks in browser, you should
+write the callback in browser and send messages to renderer. And also make use
+of DOM's events like `unload` and `beforeunload`, they will work perfectly.
+
+## remote.require(module)
+
+* `module` String
+
+Return a module in browser.
+
+## remote.getCurrentWindow()
+
+Return the `BrowserWindow` object that represents current window.
+
+`Note:` it doesn't return the `window` object which represents the global
+scope, instead it returns an instance of the `BrowserWindow` class which is
+created with `browser-window` module in browser.
+
+## remote.getGlobal(name)
+
+* `name` String
+
+Return the `global[name]` value in browser.
+
+## remote.process
+
+Getter to return the `process` object in browser, this is the same with
+`remote.getGlobal('process')` but gets cached.