Fleshed out event documentation

docs/guide/events.md

@@ -3,36 +3,95 @@ Events
 
 TBD, see also [Component.md](../api/base/Component.md).
 
-There is no longer the need to define an `on`-method in order to define an event in Yii 2.0.
-Instead, you can use whatever event names. To attach a handler to an event, you should
-use the `on` method now:
+[[ADD INTRODUCTION]]
+
+Creating Event Handlers
+-----------------------
+
+In Yii 1, events were defined using the `onEventName` method syntax, such as `onBeforeSave`. This is no longer necessary in Yii 2, as event handling is now assigned using the `on` method. The method's first argument is the name of the event to watch for; the second is the handling method to be called when that event occurs:
 
 ```php
 $component->on($eventName, $handler);
-// To detach the handler, use:
+```
+
+[[LINK TO LIST OF EVENTS]]
+
+The handler must be a valid PHP callback. This could be represented as:
+
+* The name of a global function
+* An array consisting of a model name and method name
+* An array consisting of an object and a method name
+* An anonymous function
+
+```php
+// Global function:
+$component->on($eventName, 'functionName');
+
+// Model and method names:
+$component->on($eventName, ['Modelname', 'functionName']);
+
+// Object and method name:
+$component->on($eventName, [$obj, 'functionName']);
+
+// Anonymous function:
+$component->on($eventName, function($event) {
+	// Use $event.
+});
+```
+
+As shown in the anonymous function example, the event handling function must be defined so that it takes one argument. This will be an [[Event]] object.
+
+
+Removing Event Handlers
+-----------------------
+
+The correspondoing `off` method removes an event handler:
+
+```php
+// $component->off($eventName);
+```
+
+Yii supports the ability to associate multiple handlers with the same event. When using `off` as in the above, every handler is removed. To remove only a specific handler, provide that as the second argument to `off`:
+
+```php
 // $component->off($eventName, $handler);
 ```
 
+The `$handler` should be presented in the `off` method in the same way as was presented in `on` in order to remove it.
+
+Event Parameters
+----------------
 
-When you attach a handler, you can now associate it with some parameters which can be later
-accessed via the event parameter by the handler:
+You can make your event handlers easier to work with and more powerful by passing additional values as parameters. 
 
 ```php
 $component->on($eventName, $handler, $params);
 ```
 
+The passed parameters will be available in the event handler through `$event->data`, which will be an array.
 
-Because of this change, you can now use "global" events. Simply trigger and attach handlers to
-an event of the application instance:
+[[NEED TO CONFIRM THE ABOVE]]
+
+Global Events
+-------------
+
+Thanks to the change in Yii 2 as to how event handlers are created, you can now use "global" events. To create a global event, simply attach handlers to an event on the application instance:
 
 ```php
 Yii::$app->on($eventName, $handler);
-....
-// this will trigger the event and cause $handler to be invoked.
+```
+
+You can use the `trigger` method to trigger these events manually:
+
+```php
+// this will trigger the event and cause $handler to be invoked:
 Yii::$app->trigger($eventName);
 ```
 
-If you need to handle all instances of a class instead of the object you can attach a handler like the following:
+Class Events
+------------
+
+You can also attach event handlers to all instances of a class instead of individual instances. To do so, use the static `Event::on` method:
 
 ```php
 Event::on(ActiveRecord::className(), ActiveRecord::EVENT_AFTER_INSERT, function ($event) {