Add describtion of `destroy` hook

README.md

@@ -185,6 +185,30 @@ The hook is only triggered when and element is to be removed from its parent –
 not if it is the child of an element that is removed. For that see the destroy
 hook.
 
+#### The `destroy` hook
+
+This hook is invoked whenever an element removed from the DOM or the child
+to an element that is being removed.
+
+
+To see the difference between this hook and the `remove` hook consider an
+example.
+
+```js
+var vnode1 = h('div', [h('div', [h('span', 'Hello')])]);
+var vnode2 = h('div', []);
+patch(container, vnode1);
+patch(vnode1, vnode2);
+```
+
+Here `destroy` is triggered for both the inner `div` element _and_ the `span`
+element it contains. `remove` on the other hand is only triggered on the `div`
+element because it is the only element being detached from its parent.
+
+You can for instance use `remove` to trigger an animation when an element is
+being removed and use the `destroy` hook to additionally animate the
+disappearance of the removed elements children.
+
 ## Modules documentation
 
 This describes the core modules. All modules are optional.