update docs, add descriptions for api methods

docs/redraw.md

@@ -1,10 +1,21 @@
 # redraw()
 
+- [Description](#description)
 - [Signature](#signature)
 - [How it works](#how-it-works)
 
 ---
 
+### Description
+
+Updates the DOM after a change in the application data layer.
+
+You DON'T need to call it if data is modified within the execution context of an event handler defined in a Mithril view, or after request completion when using `m.request`/`m.jsonp`.
+
+You DO need to call it in `setTimeout`/`setInterval`/`requestAnimationFrame` callbacks, or callbacks from 3rd party libraries.
+
+---
+
 ### Signature
 
 `m.redraw()`