Update README.md

Author: wbuchwalter

README.md

@@ -3,7 +3,7 @@
 
 For Angular 2 see [ng2-redux](https://github.com/wbuchwalter/ng2-redux).
 
-**Warning: The API will be subject to breaking changes until `1.0.0` is released. You can follow progress on the `bc-1.0.0` branch**
+**Warning: The API will be subject to breaking changes until `1.0.0` is released.**
 
 [![build status](https://img.shields.io/travis/wbuchwalter/ng-redux/master.svg?style=flat-square)](https://travis-ci.org/wbuchwalter/ng-redux)
 [![npm version](https://img.shields.io/npm/v/ng-redux.svg?style=flat-square)](https://www.npmjs.com/package/ng-redux)
@@ -20,6 +20,8 @@ For Angular 2 see [ng2-redux](https://github.com/wbuchwalter/ng2-redux).
 - [Using DevTools](#using-devtools)
 
 ## Installation
+
+**The current npm version is outdated, and will be updated once 1.0.0 is finished**
 ```js
 npm install --save ng-redux
 ```
@@ -30,7 +32,7 @@ npm install --save ng-redux
 
 ```JS
 import reducers from './reducers';
-import {combineReducers} from 'redux';
+import { combineReducers } from 'redux';
 import loggingMiddleware from './loggingMiddleware';
 import 'ng-redux';
 
@@ -42,18 +44,21 @@ angular.module('app', ['ngRedux'])
 ```
 
 #### Usage
+*Note: this sample is using the ControllerAs syntax, usage is slightly different without ControllerAs, see API section for more details*
+
 ```JS
- export default function todoLoader() {
-  return {
-    controllerAs: 'vm',
-    controller: TodoLoaderController,
-    template: "<div ng-repeat='todo in vm.todos'>{{todo.text}}</div>"
-  };
-}
+import * as CounterActions from '../actions/counter';
 
-class TodoLoaderController {
-  constructor($ngRedux) {
-    $ngRedux.connect(state => ({todos: state.todos}), this);
+class CounterController {
+  constructor($ngRedux, $scope) {
+    $ngRedux.connect($scope, this.mapStateToScope, CounterActions, 'vm');
+  }
+
+  // Which part of the Redux global state does our component want to receive on $scope?
+  mapStateToScope(state) {
+    return {
+      counter: state.counter
+    };
   }
 }
 ```
@@ -70,20 +75,18 @@ Creates the Redux store, and allow `connect()` to access it.
 * [`storeEnhancers`] \(*Function[]*): Optional, this will be used to create the store, in most cases you don't need to pass anything, see [Store Enhancer official documentation.](http://rackt.github.io/redux/docs/Glossary.html#store-enhancer)
 
 
-### `connect([mapStateToTarget], [target])`
+### `connect([scope], [mapStateToScope], [mapDispatchToScope], [propertyKey])`
 
 Connects an Angular component to Redux.
 
 #### Arguments
-* [`mapStateToTarget`] \(*Function*): connect will subscribe to Redux store updates. Any time it updates, mapStateToTarget will be called. Its result must be a plain object, and it will be merged into `target`.
-* [`target`] \(*Object*): A plain object, this will be use as a target by `mapStateToTarget`. Read the Remarks below about the implication of passing `$scope` to `connect`.
-
-#### Returns
-(*Function*): A function that unsubscribes the change listener.
+* [`scope`] \(*Object*): The `$scope` of your controller.
+* [`mapStateToScope`] \(*Function*): connect will subscribe to Redux store updates. Any time it updates, mapStateToTarget will be called. Its result must be a plain object, and it will be merged into `target`.
+* [`mapDispatchToScope`] \(*Object* or *Function*): If an object is passed, each function inside it will be assumed to be a Redux action creator. An object with the same function names, but bound to a Redux store, will be merged into your component `$scope`. If a function is passed, it will be given `dispatch`. It’s up to you to return an object that somehow uses `dispatch` to bind action creators in your own way. (Tip: you may use the [`bindActionCreators()`](http://gaearon.github.io/redux/docs/api/bindActionCreators.html) helper from Redux.).
+* [`propertyKey`] \(*string*): If provided, `mapStateToScope` and `mapDispatchToScope` will merge onto `$scope[propertyKey]`. This is needed especially when using the `ControllerAs` syntax: in this case you should provide the same value than the value provided to controllerAs (e.g: `'vm'`). When not using `ControllerAs` syntax, you are free to omit this argument, everything will be merged directly onto `$scope`.
 
 #### Remarks
-If `$scope` is passed to `connect` as `target`, ngRedux will listen to the `$destroy` event and unsubscribe the change listener when it is triggered, you don't need to keep track of your subscribtions in this case.
-If anything else than `$scope` is passed as target, the responsability to unsubscribe correctly is deferred to the user.
+As `$scope` is passed to `connect`, ngRedux will listen to the `$destroy` event and unsubscribe the change listener itself, you don't need to keep track of your subscribtions.
 
 ### Store API
 All of redux's store methods (i.e. `dispatch`, `subscribe` and `getState`) are exposed by $ngRedux and can be accessed directly. For example:
@@ -92,6 +95,8 @@ All of redux's store methods (i.e. `dispatch`, `subscribe` and `getState`) are e
 redux.bindActionCreators(actionCreator, $ngRedux.dispatch);
 ```
 
+This means that you are free to use Redux basic API in advanced cases where `connect`'s API would not fill your needs.
+
 
 ## Using DevTools
 In order to use Redux DevTools with your angular app, you need to install [react](https://www.npmjs.com/package/react), [react-redux](https://www.npmjs.com/package/react-redux) and [redux-devtools](https://www.npmjs.com/package/redux-devtools) as development dependencies.