doc: add more

[ci skip]

README.markdown

@@ -7,7 +7,7 @@
 
 **_An enhanced HTTP/RESTful API Client_**
 
-_rail_ is a io.js/node.js HTTP client supporting https, http and [http2](https://www.npmjs.com/package/http2).
+_rail_ is an io.js/node.js HTTP client supporting https, http and [http2](https://www.npmjs.com/package/http2).
 
 A set of built-in plugins, currently featuring [`buffer`](./doc/plugins.markdown#buffer), [`cookies`](./doc/plugins.markdown#cookies), [`redirect`](./doc/plugins.markdown#redirect), [`json`](./doc/plugins.markdown#json), [`timeout`](./doc/plugins.markdown#timeout) & [`validate`](./doc/plugins.markdown#validate) simplify making requests,
 and a powerful event-driven plugin interface aids in the implementation of complex automated RESTful API calls.
@@ -32,9 +32,9 @@ Stability: 2 - Unstable
     - [Request & Plugin Options](#request--plugin-options)
     - [Custom Client](#custom-client)
   - [Use as a drop-in replacement](#use-as-a-drop-in-replacement)
-  - [API](./doc/api.markdown)
   - [Plugins](./doc/plugins.markdown)
-  - [Plugin API](./doc/plugin-api.markdown) - _the internals of RAIL_
+  - [API](./doc/api.markdown)
+  - [Plugin API](./doc/plugin-api.markdown)
   - [Tests](#tests)
   - [ChangeLog](./CHANGELOG.markdown)
   - [License](./LICENSE)
@@ -144,23 +144,17 @@ call.end('world');
 [back to top](#table-of-contents)
 
 ## Use as a drop-in replacement
-_rail_ does not support the following request options
-
-  - `hostname`
-  - `localAddress`
-  - `socketPath`
+_rail_ does **not** support the `hostname`, `localAddress` & `socketPath` options, see [rail.call()](./doc/api.markdown#railcallopt_options-opt_responselistener) for more information.
 
-**When not using https**: make sure to set the correct default protocol
+When **not** using **https**, make sure to set the correct default protocol
 
 ```js
 var RAIL = require('rail');
-
 RAIL.proto = 'http';
-
 ```
-... then replace every call to `http.request` with `RAIL.call`.
+... and then replace every call to `http.request` with `RAIL.call`.
 
-Alternatively create a custom client with defaults & plugins configured to your needs.
+_Alternatively_ create a custom client with defaults & plugins configured to your needs.
 
 [back to top](#table-of-contents)
 

doc/api.markdown

@@ -75,10 +75,13 @@ When `opt_options` is a string, it is handled like `opt_options.url`.
 
   - `{string} proto` - See [`new RAIL(opt_options)`](#new-railopt_options)
   - `{string} url` - When given, the request options are set accordingly
-  - `{Object} request` - request options, see `https.request()`
+  - `{Object} request` - request options, see [io.js](https://iojs.org/api/https.html#https_https_request_options_callback) or [node.js](https://nodejs.org/api/https.html#https_https_request_options_callback)
   - `{Object|boolean} *` - plugin options
 
-_Note: For convenience & compatibility with node core API, all request options can also be provided directly besides proto & plugin options._
+_Notes_
+
+  - _request options `hostname`, `localAddress` & `socketPath` are not supported_
+  - _request options can also be provided directly besides proto & plugin options_
 
 [back to top](#table-of-contents)
 

doc/plugin-api.markdown

@@ -1,47 +1,48 @@
 # [rail](../README.markdown) Plugin API
 
+The `RAIL` object emits `plugin-*` events that correspond to different states of a single request inside a call.
+These events enable plugins to monitor the state of a request, as well as modify the request configuration and when necessary intercept _user_ events on the `Call` object.
+
+The `Call` object provides a plugin interface for interception of _user_ events & request management.
+
+All methods for the plugin interface begin with two underscores `__`.
+
 ## Table of Contents
 
-  - [RAIL Plugin Events](#rail-plugin-events)
+  - [Plugin Events](#plugin-events)
   - [Interceptable Events](#interceptable-events)
   - [Request Management](#request-management)
 
-## Basics
-
-  - Methods beginning with two underscores `__` are defined as plugin API
-
 ## Example
+A _class_ implementing a very simple plugin that emits `my` event every time a request configuration has been created.
 
 ```js
-function myPlugin(rail, opt_options) {
-  opt_options = opt_options || {};
-
-  var pluginOptions = {
-
-  };
+function MyPlugin(rail, options) {
+  if (!(this instanceof MyPlugin)) {
+    return new MyPlugin(rail, options);
+  }
+  this._rail = rail;
 
+  this._setup();
+}
+module.exports = MyPlugin;
 
-  function interceptResponse(call, options, response) {
-    // do something async
-    //   ... then
-    call.__emit('response', response);
-  }
 
+MyPlugin.prototype._setup = function() {
+  var self = this;
+  var rail = this._rail;
 
-  rail.on('plugin-response', function(call, options, response) {
+  rail.on('plugin-configure', function(call, options) {
     if (options.my) {
-      call.__intercept('response', interceptResponse);
+      call.emit('my', 'works!');
     }
   });
-
-  return pluginOptions;
-}
-module.exports = myPlugin;
+};
 ```
 
 [back to top](#table-of-contents)
 
-## RAIL Plugin Events
+## Plugin Events
 
 These events are emitted on the `RAIL` object.
 

doc/plugins.markdown

@@ -82,6 +82,7 @@ A configurable redirect mechanism.
 _Note_: When no request options are supplied, the plugin defaults apply.
 
 ### Event: 'redirect'
+Emitted when `request.end()` of a redirected request has been called.
 
 `function({Object} options)`
 
@@ -105,7 +106,7 @@ _Note_: The socket idle timeout is only supported for https & http.
 _Note_: When no request options are supplied, the plugin defaults apply.
 
 ### Event: 'timeout'
-Emitted on the `call` object when a timeout occurs.
+Emitted on the `call` object when a timeout occurs. It is up to the user to abort the call.
 
 `function({string} type, {Object} options)`