New documentation structure

Author: Vlad Balin

docs/chapters/Events.md

@@ -23,51 +23,18 @@ class Messenger {
 
 > `Messenger` abstract base class is included with Type-R, see below.
 
-### eventsSource.trigger(event, arg1, arg2, ... )
+### trigger(event, arg1, arg2, ... )
 
 Trigger callbacks for the given event, or space-delimited list of events. Subsequent arguments to trigger will be passed along to the event callbacks.
 
-## Messenger
-
-Messenger is an abstract base class implementing Events mixin and some convenience methods.
-As all Type-R classes, its definition must be preceded with the `@define` decorator.
-
-```javascript
-import { define, Messenger } from 'type-r'
-
-@define class MyMessenger extends Messenger {
-
-}
-```
-
-### `readonly` messenger.cid
-
-Unique run-time only messenger instance id (string).
-
-### messenger.initialize()
-
-Callback which is called at the end of the constructor.
-
-### messenger.dispose()
-
-Executes `messenger.stopListening()` and `messenger.off()`.
-
-Objects must be disposed to prevent memory leaks caused by subscribing for events from singletons.
-
-## High-level listening API
-
-All high-level event subscriptions are stopped automatically on the listener's disposal, and thus does not introduce memory leaks.
-
-This is the preferable listening API and must be used in all application code.
-
-### listener.listenTo(other, event, callback)
+### listenTo(source, event, callback)
 Tell an object to listen to a particular event on an other object. The advantage of using this form, instead of other.on(event, callback, object), is that listenTo allows the object to keep track of the events, and they can be removed all at once later on. The callback will always be called with object as context.
 
 ```javascript
     view.listenTo(record, 'change', view.render );
 ```
 
-### listener.stopListening([other], [event], [callback])
+### stopListening([source], [event], [callback])
 
 Tell an object to stop listening to events. Either call stopListening with no arguments to have the object remove all of its registered callbacks ... or be more precise by telling it to remove just the events it's listening to on a specific object, or a specific event, or just a specific callback.
 
@@ -79,15 +46,11 @@ Tell an object to stop listening to events. Either call stopListening with no ar
 
 All Type-R classes execute `this.stopListening()` from their `dispose()` method.
 
-### listener.listenToOnce(other, event, callback)
+### listenToOnce(source, event, callback)
 
 Just like listenTo, but causes the bound callback to fire only once before being removed.
 
-## Low-level listening API
-
-This API is more efficient but requires manual action to stop the subscription. Must be used with care.
-
-### eventSource.on(event, callback, [context])
+### on(event, callback, [context])
 
 Bind a callback function to an object. The callback will be invoked whenever the event is fired. If you have a large number of different events on a page, the convention is to use colons to namespace them: `poll:start`, or `change:selection`. The event string may also be a space-delimited list of several events...
 
@@ -115,7 +78,7 @@ All event methods also support an event map syntax, as an alternative to positio
 
 To supply a context value for this when the callback is invoked, pass the optional last argument: `record.on('change', this.render, this)` or `record.on({change: this.render}, this)`.
 
-### eventSource.off([event], [callback], [context])
+### off([event], [callback], [context])
 
 Remove a previously bound callback function from an object. If no context is specified, all of the versions of the callback with different contexts will be removed. If no callback is specified, all callbacks for the event will be removed. If no event is specified, callbacks for all events will be removed.
 
@@ -138,32 +101,60 @@ Remove a previously bound callback function from an object. If no context is spe
 
 Note that calling `record.off()`, for example, will indeed remove all events on the record — including events that Backbone uses for internal bookkeeping.
 
-### eventsSource.once(event, callback, [context])
+### once(event, callback, [context])
 Just like `on()`, but causes the bound callback to fire only once before being removed. Handy for saying "the next time that X happens, do this". When multiple events are passed in using the space separated syntax, the event will fire once for every event you passed in, not once for a combination of all events
 
-## Record events
+## Messenger class
 
-### `event` "change:attrName" (record, value, options)
+Messenger is an abstract base class implementing Events mixin and some convenience methods.
 
-When a specific attribute has been updated
+```javascript
+import { define, Messenger } from 'type-r'
+
+class MyMessenger extends Messenger {
+
+}
+```
+
+### `implements` Events
+
+Messenger implements [Events](#events-mixin) mixin.
+ 
+### cid
+
+Unique run-time only messenger instance id (string).
+
+### initialize()
+
+Callback which is called at the end of the constructor.
+
+### dispose()
+
+Executes `messenger.stopListening()` and `messenger.off()`.
+
+Objects must be disposed to prevent memory leaks caused by subscribing for events from singletons.
+
+## Built-in events
 
 ### `event` "change" (record, options)
 
-When a record's attributes have changed.
+When a record's attributes have changed. Triggered by both record and collection containing the record.
 
-## Collection events
+### `event` "change:attrName" (record, value, options)
+
+When a specific record's attribute has been updated
 
 ### `event` "changes" (collection, options)
 
-The main change event. Single event triggered when the collection has been changed.
+When collection has changed. Single event triggered when the collection has been changed.
 
-### `event` "update" (collection, options)
+### `event` "reset" (collection, options)
 
-Single event triggered after any number of records have been added or removed from a collection.
+When the collection's entire contents have been reset (`reset()` method was called).
 
-### `event` "reset" (collection, options)
+### `event` "update" (collection, options)
 
-When the collection's entire contents have been reset.
+Single event triggered after any number of records have been added or removed from a collection.
 
 ### `event` "sort" (collection, options)
 
@@ -177,6 +168,3 @@ When a record is added to a collection.
 
 When a record is removed from a collection.
 
-### `event` "change" (record, options)
-
-When a record's attributes have changed.