Finalized Events chapter

Author: Vlad Balin

docs/chapters/Events.md

@@ -1,40 +1,38 @@
 # Events
 
-Both `Record` and `Collection` uses an efficient synchronous events implementation which is compatible with Backbone 1.1 Events API but is twice faster in average. It comes in form of `Events` mixin and the `Messenger` base class.
-
-An implementation is optimized for the large amount of relatively small subscriptions (5-10 events). Here are the benchmark results (lower is the better).
-
-![performance](./events-performance.jpg)
-
-It is also available separately as part of [MixtureJS](https://github.com/Volicon/MixtureJS) package.
+Type-R uses an efficient synchronous events implementation which is backward compatible with Backbone 1.1 Events API but is about twice faster in all major browsers. It comes in form of `Events` mixin and the `Messenger` base class.
 
 ## Events mixin
 
-`Events` is a [mixin](11_Mixins.md) giving the object the ability to bind and trigger custom named events. Events do not have to be declared before they are bound, and may take passed arguments.
+`Events` is a [mixin](#mixins) giving the object the ability to bind and trigger custom named events. Events do not have to be declared before they are bound, and may take passed arguments.
+
+Both `source` and `listener` mentioned in method signatures must implement Events methods.
 
 ```javascript
 import { mixins, Events } from 'type-r'
 
 @mixins( Events )
-class Messenger {
+class EventfulClass {
     ...
 }
 ```
 
-> `Messenger` abstract base class is included with Type-R, see below.
+<aside class="notice">There's the <code>Messenger</code> abstract base class with Events mixed in.</aside>
 
-### trigger(event, arg1, arg2, ... )
+### source.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.
 
-### listenTo(source, event, callback)
+### listener.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 );
 ```
 
-### stopListening([source], [event], [callback])
+<aside class="success">Subscriptions made with <code>listenTo()</code> will be stopped automatically if an object is properly disposed (<code>dispose()</code> method is called).</aside>
+
+### listener.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.
 
@@ -44,13 +42,13 @@ Tell an object to stop listening to events. Either call stopListening with no ar
     view.stopListening(record); // Unsubscribe from all events from the record
 ```
 
-All Type-R classes execute `this.stopListening()` from their `dispose()` method.
+<aside class="notice">Messenger, Record, Collection, and Store execute <code>this.stopListening()</code> from their <code>dispose()</code> method. You don't have to unsubscribe from events explicitly if you are using <code>listenTo()</code> method and disposing your objects properly.</aside>
 
-### listenToOnce(source, event, callback)
+### listener.listenToOnce(source, event, callback)
 
-Just like listenTo, but causes the bound callback to fire only once before being removed.
+Just like `listenTo()`, but causes the bound callback to fire only once before being automatically removed.
 
-### on(event, callback, [context])
+### source.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...
 
@@ -78,7 +76,9 @@ 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)`.
 
-### off([event], [callback], [context])
+<aside class="warning">Event subscription with <code>source.on()</code> may create memory leaks if it's not stopped properly with <code>source.off()</code></aside>
+
+### source.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.
 
@@ -101,7 +101,7 @@ 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.
 
-### once(event, callback, [context])
+### source.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
 
 ## Messenger class
@@ -120,51 +120,43 @@ class MyMessenger extends Messenger {
 
 Messenger implements [Events](#events-mixin) mixin.
 
-### cid
+### messenger.cid
 
 Unique run-time only messenger instance id (string).
 
-### initialize()
+### `callback` messenger.initialize()
 
 Callback which is called at the end of the constructor.
 
-### dispose()
+### messenger.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. Triggered by both record and collection containing the record.
-
-### `event` "change:attrName" (record, value, options)
-
-When a specific record's attribute has been updated
-
-### `event` "changes" (collection, options)
-
-When collection has changed. Single event triggered when the collection has been changed.
-
-### `event` "reset" (collection, options)
-
-When the collection's entire contents have been reset (`reset()` method was called).
-
-### `event` "update" (collection, options)
+All Type-R objects implement Events mixin and use events to notify listeners on changes.
 
-Single event triggered after any number of records have been added or removed from a collection.
+Record and Store change events:
 
-### `event` "sort" (collection, options)
+Event name | Handler arguments | When triggered
+-------|-------------------|------------
+change | (record, options) | At the end of any changes.
+change:attrName | (record, value, options) | The record's attribute has been changed.
 
-When the collection has been re-sorted.
+Collection change events:
 
-### `event` "add" (record, collection, options)
+Event name | Handler arguments | When triggered
+-------|-------------------|------------
+changes | (collection, options) | At the end of any changes.
+reset | (collection, options) | `reset()` method was called.
+update | (collection, options) | Any records added or removed.
+sort | (collection, options) | Order of records is changed. 
+add | (record, collection, options) | The record is added to a collection.
+remove | (record, collection, options) | The record is removed from a collection.
+change | (record, options) | The record is changed inside of collection.
 
-When a record is added to a collection.
 
-### `event` "remove" (record, collection, options)
 
-When a record is removed from a collection.
 

docs/chapters/collection.md

@@ -73,12 +73,7 @@ Initialization function which is called at the end of the constructor.
 
 ### collection.createSubset()
 
-## Read and Update
-
-Methods to update the collection. They accept common options:
-
-- `sort : false` - do not sort the collection.
-- `parse : true` - parse raw JSON (used to set collection with a data from the server).
+## Read and iterate
 
 ### collection.get( id )
 Get a record from a collection, specified by an `id`, a `cid`, or by passing in a record.
@@ -98,6 +93,59 @@ Like an array, a Collection maintains a length property, counting the number of
 
 Raw access to the JavaScript array of records inside of the collection. Usually you'll want to use `get`, `at`, or the other methods to access record objects, but occasionally a direct reference to the array is desired.
 
+### collection.slice( begin, end )
+
+Return a shallow copy of the `collection.models`, using the same options as native Array#slice.
+
+### collection.indexOf( recordOrId : any ) : number
+
+Return an index of the record in the collection, and -1 if there are no such a record in the collection.
+
+Can take the record itself as an argument, `id`, or `cid` of the record.
+
+### collection.forEach( iteratee : ( val : Record, index ) => void, context? )
+
+Same as `collection.each()`.
+
+### collection.each( iteratee : ( val : Record, index ) => void, context? )
+
+Iterate through the elements of the collection. Similar to `Array.forEach`.
+
+<aside class="notice">Use <code>collection.updateEach( iteratee, index )</code> method to update records in a loop.</aside>
+
+### collection.map( iteratee : ( val : Record, index ) => T, context? )
+
+Map elements of the collection. Similar to `Array.map`, but `undefined` values returned by iteratee are filtered out.
+
+Thus, `collection.map` can be used to map and filter elements in a single pass.
+
+### collection.filter( iteratee : Predicate, context? )
+
+Return filtered array of records matching the predicate.
+
+Predicate is either the iteratee function returning boolean, or an object with attribute values used to match with record's attributes.
+
+### collection.every( iteratee : Predicate, context? ) : boolean
+
+Return `true` if all records match the predicate.
+
+### collection.some( iteratee : Predicate, context? ) : boolean
+
+Return `true` if at least one record match the predicated.
+
+By default there is no comparator for a collection. If you define a comparator, it will be used to maintain the collection in sorted order. This means that as records are added, they are inserted at the correct index in `collection.models`.
+
+Note that Type-R depends on the arity of your comparator function to determine between the two styles, so be careful if your comparator function is bound.
+
+Collections with a comparator will not automatically re-sort if you later change record attributes, so you may wish to call sort after changing record attributes that would affect the order.
+
+## Update
+
+Methods to update the collection. They accept common options:
+
+- `sort : false` - do not sort the collection.
+- `parse : true` - parse raw JSON (used to set collection with a data from the server).
+
 ### collection.add( records, options? )
 
 Add a record (or an array of records) to the collection. If this is the `Record.Collection`, you may also pass raw attributes objects, and have them be vivified as instances of the `Record`. Returns the added (or preexisting, if duplicate) records.
@@ -165,7 +213,7 @@ Any additional changes made to the collection or its items in event handlers wil
 
 ### collection.updateEach( iteratee : ( val : Record, index ) => void, context? )
 
-Similar to the `collection.each`, but wraps the loop in a transaction.
+Similar to the `collection.each`, but wraps an iteration in a transaction. The single `changes` event will be emitted for the group of changes to the records made in `updateEach`.
 
 ### collection.push( record, options? )
 
@@ -181,16 +229,6 @@ Add a record at the beginning of a collection. Takes the same options as add.
 ### collection.shift( options? )
 Remove and return the first record from a collection. Takes the same options as remove.
 
-### collection.slice( begin, end )
-
-Return a shallow copy of the `collection.models`, using the same options as native Array#slice.
-
-### collection.indexOf( recordOrId : any ) : number
-
-Return an index of the record in the collection, and -1 if there are no such a record in the collection.
-
-Can take the record itself as an argument, `id`, or `cid` of the record.
-
 ## Change events
 
 Object tree formed by nested records is deeply observable by default; changes in every item trigger change events for the collection and all parent elements in sequence.
@@ -215,48 +253,33 @@ Subscribe for events from records. The `hander` is either the collection's metho
 
 When `true` is passed as a handler, the corresponding event will be triggered on the collection.
 
-## Iteration
+### `event` "changes" (collection, options)
 
-### collection.forEach( iteratee : ( val : Record, index ) => void, context? )
+When collection has changed. Single event triggered when the collection has been changed.
 
-Same as `collection.each()`.
+### `event` "reset" (collection, options)
 
-### collection.each( iteratee : ( val : Record, index ) => void, context? )
+When the collection's entire contents have been reset (`reset()` method was called).
 
-Iterate through the elements of the collection. Similar to `Array.forEach`.
-
-### collection.updateEach( iteratee : ( val : Record, index ) => void, context? )
-
-Similar to the `collection.each`, but wraps an iteration in a transaction. The single `changes` event will be emitted
-for the group of changes to the records made in `updateEach`.
-
-*Use this method if you modify records in a loop*.
-
-### collection.map( iteratee : ( val : Record, index ) => T, context? )
-
-Map elements of the collection. Similar to `Array.map`, but `undefined` values returned by iteratee are filtered out.
-
-Thus, `collection.map` can be used to map and filter elements in a single pass.
+### `event` "update" (collection, options)
 
-### collection.filter( iteratee : Predicate, context? )
+Single event triggered after any number of records have been added or removed from a collection.
 
-Return filtered array of records matching the predicate.
+### `event` "sort" (collection, options)
 
-Predicate is either the iteratee function returning boolean, or an object with attribute values used to match with record's attributes.
+When the collection has been re-sorted.
 
-### collection.every( iteratee : Predicate, context? ) : boolean
+### `event` "add" (record, collection, options)
 
-Return `true` if all records match the predicate.
+When a record is added to a collection.
 
-### collection.some( iteratee : Predicate, context? ) : boolean
+### `event` "remove" (record, collection, options)
 
-Return `true` if at least one record match the predicated.
+When a record is removed from a collection.
 
-By default there is no comparator for a collection. If you define a comparator, it will be used to maintain the collection in sorted order. This means that as records are added, they are inserted at the correct index in `collection.models`.
+### `event` "change" (record, options)
 
-Note that Type-R depends on the arity of your comparator function to determine between the two styles, so be careful if your comparator function is bound.
-
-Collections with a comparator will not automatically re-sort if you later change record attributes, so you may wish to call sort after changing record attributes that would affect the order.
+When a record inside of the collection is changed.
 
 ## Sorting