Merge pull request #28 from BigBlueHat/patch-2

added note about $data and mutation object

Author: yyx990803

source/api/instance-methods.md

@@ -10,9 +10,23 @@ order: 4
 ### vm.$watch( keypath, callback )
 
 - **keypath** `String`
-- **callback( newValue )** `Function`
+- **callback( newValue, [mutation])** `Function`
 
-Watch a keypath on the vm's data object for changes and call the callback with the new value.
+Watch a keypath on the vm's data object (or the `$data` object itself) for changes and call the callback with the new value.
+
+A second `mutation` object is also available and is useful when watching arrarys:
+
+```javascript
+this.$watch('list', function (value, mutation) {
+    if (mutation) {
+        mutation.method // e.g. 'push'
+        mutation.args // raw arguments to the mutation method
+        mutation.result // return value
+        mutation.inserted // new, inserted elements
+        mutation.removed // removed elements
+    }
+})
+```
 
 ### vm.$unwatch( keypath, [callback] )
 
@@ -110,4 +124,4 @@ Remove the vm's `$el` from the DOM.
 
 ### vm.$destroy()
 
-Completely destroy a vm. Clean up its connections with other existing vms, unbind all its directives and remove its `$el` from the DOM. Also, all `$on` and `$watch` listeners will be automatically removed.
+Completely destroy a vm. Clean up its connections with other existing vms, unbind all its directives and remove its `$el` from the DOM. Also, all `$on` and `$watch` listeners will be automatically removed.