doc/plugin-api: major overhaul

doc/plugin-api.markdown

@@ -32,26 +32,52 @@ module.exports = myPlugin;
 
 ## RAIL Plugin Events
 
-### 'plugin-call'
+These events are emitted on the `RAIL` object.
+
+### Event: 'plugin-call'
+Emitted when a new `Call` object is created.
 
 `function(Call, ?Object=)`
 
-### 'plugin-configure'
+### Event: 'plugin-configure'
+Emitted after a new request configuration has been pushed onto the stack.
 
 `function(Call, Object)`
 
-### 'plugin-request'
+### Event: 'plugin-request'
+Emitted directly after the request object has been created.
 
 `function(Call, Object, Request)`
 
-### 'plugin-response'
+### Event: 'plugin-response'
+Emitted when the response headers have been received.
 
 `function(Call, Object, Response)`
 
 ## Interceptable Events
+Specific events emitted on the `Call` object can be intercepted.
+These _interceptable events_ are designed to gain complete control over the request workflow and allow implementing even non-trivial & asynchronous features as a plugin.
+
+As an example for such a non-trivial feature see the [redirect plugin](../lib/plugins/redirect.js).
+
+The methods beginning with two underscores `__` are defined as plugin interface.
+
+### call.\_\_emit(event, var_args)
+Invokes the next pending interceptor or emits the event.
+
+On each call to `__emit()` only one interceptor is invoked, this way plugins can _blackhole_ responses by not calling `__emit()` after the response has been processed.
+
+### call.\_\_intercept(event, interceptor)
+Registers an interceptor `function(Call, Object, *)` for an event.
+
+### call.\_\_clear()
+Removes all registered interceptors.
 
-### 'request'
+### Event: 'request'
+Emitted one tick after the request object has been created.
 
-### 'response'
+### Event: 'response'
+Emitted after the response headers have been received.
 
-### 'error'
+### Event: 'error'
+Emitted on an error in context of a request.