Update populate docs with more clear example. Fixed typo in roles recipe.

Author: prescottprue

README.md

@@ -45,18 +45,18 @@ npm install --save react-redux-firebase
 
 The above install command will install the `@latest` tag. You may also use the following tags when installing to get different versions:
 
-* `@next` - Next upcoming release. currently points to active progress with `v1.5.0-*` pre-releases
+* `@next` - Next upcoming release. Currently points to active progress with `v1.5.0-*` pre-releases
 * `@canary` - Most possible up to date code. Currently points to active progress with `v2.0.0-*` pre-releases. *Warning:* Syntax is different than current stable version.
 
 Other versions docs are available using the dropdown on the above docs link. For quick access:
 * [Version `1.5.0` Docs](http://docs.react-redux-firebase.com/history/v1.5.0/)
 * [Version `2.0.0` Docs](http://docs.react-redux-firebase.com/history/v2.0.0/)
 
-**Note:** Be aware of changes when using version that are tagged `@latest`. Please report any issues you encounter, and try to keep an eye on the [releases page](https://github.com/prescottprue/react-redux-firebase/releases) for relevant release info.
+Be aware of changes when using version that are tagged `@latest`. Please report any issues you encounter, and try to keep an eye on the [releases page](https://github.com/prescottprue/react-redux-firebase/releases) for updates.
 
 ## Use
 
-**NOTE:** If you are just starting a new project, you might want to use [`v2.0.0`](http://docs.react-redux-firebase.com/history/v2.0.0/#use) has an even easier syntax. For clarity on the transition, view the [`v1` -> `v2` migration guide](http://docs.react-redux-firebase.com/history/v2.0.0/docs/v2-migration-guide.html)
+**Note:** If you are just starting a new project, you may want to use [`v2.0.0`](http://docs.react-redux-firebase.com/history/v2.0.0/#use) since it is has an even easier syntax. For clarity on the transition, view the [`v1` -> `v2` migration guide](http://docs.react-redux-firebase.com/history/v2.0.0/docs/v2-migration-guide.html)
 
 Include `reactReduxFirebase` in your store compose function and  `firebaseStateReducer` in your reducers:
 
@@ -277,7 +277,7 @@ The [examples folder](/examples) contains full applications that can be copied/a
   * [populate functionality](http://react-redux-firebase.com/docs/populate) (similar to mongoDB or SQL JOIN)
   * `react-native` support ([web/js](http://react-redux-firebase.com/docs/recipes/react-native.html) or native modules through [`react-native-firebase`](http://docs.react-redux-firebase.com/history/v2.0.0/docs/recipes/react-native.html#native-modules))
   * tons of [integrations](#integrations)
-  * [`profileDecorator`](http://react-redux-firebase.com/docs/config) - change format of profile stored on Firebase
+  * [`profileFactory`](http://react-redux-firebase.com/docs/config) - change format of profile stored on Firebase
   * [`getFirebase`](http://react-redux-firebase.com/docs/thunks) - access to firebase instance that fires actions when methods are called
   * [access to firebase's `storage`](http://react-redux-firebase.com/docs/storage) method`
   * `uniqueSet` method helper for only setting if location doesn't already exist

docs/populate.md

@@ -2,36 +2,62 @@
 
 Populate allows you to replace IDs within your data with other data from Firebase. This is very useful when trying to keep your data flat. Some would call it a _join_, but it was modeled after [the mongo populate method](http://mongoosejs.com/docs/populate.html).
 
+Initial data from populate is placed into redux in a normalized pattern [following defined redux practice of normalizing](http://redux.js.org/docs/recipes/reducers/NormalizingStateShape.html). `populatedDataToJS` helper used in the `connect` function then builds populated data out of normalized data within redux (**NOTE:** This does not apply if you are using `v1.1.5` or earlier).
+
+A basic implementation can look like so:
+```javascript
+const populates = [
+  { child: 'owner', root: 'users' } // replace owner with user object
+]
+
+@firebaseConnect([
+  // passing populates parameter also creates all necessary child queries
+  { path: 'todos', populates }
+])
+@connect(({ firebase }) => ({
+  // populate original from data within separate paths redux
+  todos: populatedDataToJS(firebase, 'todos', populates),
+  // dataToJS(firebase, 'todos') for unpopulated todos
+}))
+```
+
+## Some Things To Note
+
+* Population happens in two parts:
+  1. `firebaseConnect` - based on populate settings, queries are created for associated keys to be replaced. Query results are stored in redux under the value of `root` in the populate settings.
+  2. `connect` - Combine original data at path with all populate data (in redux from queries created by passing populate settings to `firebaseConnect`)
+* Populate creates a query for each key that is being replaced
+* Results of populate queries are placed under their root
+
+## Examples
+
 List of todo items where todo item can contain an owner parameter which is a user's UID like so:
 
 ```json
-{ text: 'Some Todo Item', owner: "Iq5b0qK2NtgggT6U3bU6iZRGyma2" }
+{ "text": "Some Todo Item", "owner": "Iq5b0qK2NtgggT6U3bU6iZRGyma2" }
 ```
 
-Populate allows you to replace the owner parameter with another value on Firebase under that key. That value you can be a string \(number and boolean treated as string\), or an object
-
-Initial data from populate is placed into redux in a normalized pattern [following defined redux practice of normalizing](http://redux.js.org/docs/recipes/reducers/NormalizingStateShape.html). `populatedDataToJS` helper used in the `connect` function then builds populated data out of normalized data within redux (**NOTE:** This does not apply if you are using `v1.1.5` or earlier).
 
 ##### Example Data
-```javascript
-todos: {
-  ASDF123: {
-    text: 'Some Todo Item',
-    owner: "Iq5b0qK2NtgggT6U3bU6iZRGyma2"
+```json
+"todos": {
+  "ASDF123": {
+    "text": "Some Todo Item",
+    "owner": "Iq5b0qK2NtgggT6U3bU6iZRGyma2"
    }
+ },
+ "displayNames": {
+   "Iq5b0qK2NtgggT6U3bU6iZRGyma2": "Morty Smith",
+   "6Ra53mf3U9Qmdwah6rXBMgY8smu1": "Rick Sanchez"
  }
- displayNames: {
-   Iq5b0qK2NtgggT6U3bU6iZRGyma2: 'Scott Prue',
-   6Ra53mf3U9Qmdwah6rXBMgY8smu1: 'Rick Sanchez'
- }
- users: {
-   Iq5b0qK2NtgggT6U3bU6iZRGyma2: {
-     displayName: 'Scott Prue',
-     email: '[email protected]'
+ "users": {
+   "Iq5b0qK2NtgggT6U3bU6iZRGyma2": {
+     "displayName": "Morty Smith",
+     "email": "[email protected]"
    },
-   6Ra53mf3U9Qmdwah6rXBMgY8smu1: {
-     displayName: 'Rick Sanchez',
-     email: '[email protected]'
+   "6Ra53mf3U9Qmdwah6rXBMgY8smu1": {
+     "displayName": "Rick Sanchez",
+     "email": "[email protected]"
    }
  }
 ```
@@ -59,7 +85,7 @@ const populates = [
 ```javascript
 ASDF123: {
   text: 'Some Todo Item',
-  owner: 'Scott Prue'
+  owner: 'Morty Smith'
  }
 ```
 
@@ -88,8 +114,8 @@ const populates = [
 ASDF123: {
   text: 'Some Todo Item',
   owner: {
-    displayName: 'Scott Prue',
-    email: '[email protected]'
+    displayName: 'Morty Smith',
+    email: '[email protected]'
   }
 }
 ```
@@ -104,25 +130,20 @@ const populates = [
   { child: 'owner', root: 'users', childParam: 'email' }
 ]
 @firebaseConnect([
- {
-   path: '/todos',
-   populates
- }
+ { path: '/todos', populates }
  // '/todos#populate=owner:users:email' // equivalent string notation
 ])
-@connect(
-  ({ firebase }) => ({
-    todos: populatedDataToJS(firebase, 'todos', populates),
-  })
-)
+@connect(({ firebase }) => ({
+  todos: populatedDataToJS(firebase, 'todos', populates),
+}))
 ```
 
 ##### Example Result
 
 ```javascript
 ASDF123: {
   text: 'Some Todo Item',
-  owner: '[email protected]'
+  owner: '[email protected]'
 }
 ```
 
@@ -192,7 +213,7 @@ const config = {
 ```
 
 ##### Example Result
-```js
+```javascript
 {
   users: {
     $uid: {

docs/recipes/roles.md

@@ -120,7 +120,7 @@ import CircularProgress from 'material-ui/CircularProgress';
  * @param {Component} componentToWrap - Component to wrap
  * @return {Component} wrappedComponent
  */
-export const UserIsAdmin = UserAuthWrapper({ // eslint-disable-line new-cap
+export const UserIsAdmin = UserAuthWrapper({
   authSelector: ({ firebase }) => {
     const user = pathToJS(firebase, 'profile');
     if (user) {
@@ -160,11 +160,12 @@ import CircularProgress from 'material-ui/CircularProgress';
  * @param {Component} componentToWrap - Component to wrap
  * @return {Component} wrappedComponent
  */
-export const UserHasPermission = permission => UserAuthWrapper({ // eslint-disable-line new-cap
+export const UserHasPermission = permission => UserAuthWrapper({
   authSelector: ({ firebase }) => {
     const user = pathToJS(firebase, 'profile');
     if (user) {
-      return { ...pathToJS(firebase, 'auth'), { user } }; // attach profile for use in predicate
+      // attach profile for use in predicate
+      return { ...pathToJS(firebase, 'auth'), user };
     }
     return pathToJS(firebase, 'auth');
   },