reorganize enumerable guide

source/object-model/enumerables.md

@@ -1,10 +1,10 @@
-## Enumerables
-
 In Ember.js, an Enumerable is any object that contains a number of child
 objects, and which allows you to work with those children using the
 [Ember.Enumerable](http://emberjs.com/api/classes/Ember.Enumerable.html) API. The most common
 Enumerable in the majority of apps is the native JavaScript array, which
-Ember.js extends to conform to the Enumerable interface.
+Ember.js extends to conform to the Enumerable interface. Ember also provides
+Ember.Set, a data structure that can efficiently answer whether it includes an
+object.
 
 By providing a standardized interface for dealing with enumerables,
 Ember.js allows you to completely change the way your underlying data is
@@ -16,51 +16,13 @@ possible. This minimizes incompatibility with other libraries, and
 allows Ember.js to use the native browser implementations in arrays
 where available.
 
-For instance, all Enumerables support the standard `forEach` method:
-
-```javascript
-[1,2,3].forEach(function(item) {
-  console.log(item);
-});
-
-//=> 1
-//=> 2
-//=> 3
-```
-
-In general, Enumerable methods, like `forEach`, take an optional second
-parameter, which will become the value of `this` in the callback
-function:
-
-```javascript
-var array = [1,2,3];
+## API Overview
 
-array.forEach(function(item) {
-  console.log(item, this.indexOf(item));
-}, array)
-
-//=> 1 0
-//=> 2 1
-//=> 3 2
-```
-
-### Enumerables in Ember.js
-
-Usually, objects that represent lists implement the Enumerable interface. Some examples:
-
- * **Array** - Ember extends the native JavaScript `Array` with the
-   Enumerable interface (unless you [disable prototype
-   extensions.](../../configuring-ember/disabling-prototype-extensions))
- * **Ember.Set** - A data structure that can efficiently answer whether it
-   includes an object.
-
-### API Overview
-
-In this guide, we'll explore some of the most common Enumerable
+In the rest of this guide, we'll explore some of the most common Enumerable
 conveniences. For the full list, please see the [Ember.Enumerable API
 reference documentation.](http://emberjs.com/api/classes/Ember.Enumerable.html)
 
-#### Iterating Over an Enumerable
+### Iterating Over an Enumerable
 
 To enumerate all the values of an enumerable object, use the `forEach` method:
 
@@ -76,7 +38,7 @@ food.forEach(function(item, index) {
 // Menu Item 3: Adobo Chicken
 ```
 
-#### Making an Array Copy
+### Making an Array Copy
 
 You can make a native array copy of any object that implements
 `Ember.Enumerable` by calling the `toArray()` method:
@@ -94,7 +56,7 @@ states.toArray()
 Note that in many enumerables, such as the `Ember.Set` used in this
 example, the order of the resulting array is not guaranteed.
 
-#### First and Last Objects
+### First and Last Objects
 
 All Enumerables expose `firstObject` and `lastObject` properties
 that you can bind to.
@@ -111,7 +73,7 @@ animals.get('lastObject');
 //=> "peacock"
 ```
 
-#### Map
+### Map
 
 You can easily transform each item in an enumerable using the
 `map()` method, which creates a new array with results of calling a
@@ -145,7 +107,7 @@ states.mapBy('capital');
 //=> ["Honolulu", "Sacramento"]
 ```
 
-#### Filtering
+### Filtering
 
 Another common task to perform on an Enumerable is to take the
 Enumerable as input, and return an Array after filtering it based on
@@ -185,7 +147,7 @@ todos.filterBy('isDone', true);
 
 If you want to return just the first matched value, rather than an Array containing all of the matched values, you can use `find` and `findBy`, which work just like `filter` and `filterBy`, but return only one item.
 
-#### Aggregate Information (All or Any)
+### Aggregate Information (All or Any)
 
 If you want to find out whether every item in an Enumerable matches some condition, you can use the `every` method:
 
@@ -223,4 +185,3 @@ Just like the filtering methods, the `every` and `some` methods have analogous `
 people.isEvery('isHappy', true) // false
 people.isAny('isHappy', true)  // true
 ```
-