Add extensive explanatory comments

As requested during code review, here's an extensive list of comments
explaining the flush() function in more detail for future maintainers.

Author: rmunn

src/runtime/internal/scheduler.ts

@@ -31,6 +31,24 @@ export function add_flush_callback(fn) {
 	flush_callbacks.push(fn);
 }
 
+// flush() calls callbacks in this order:
+// 1. All beforeUpdate callbacks, in order: parents before children
+// 2. All bind:this callbacks, in reverse order: children before parents.
+// 3. All afterUpdate callbacks, in order: parents before children. EXCEPT
+//    for afterUpdates called during the initial onMount, which are called in
+//    reverse order: children before parents.
+// Since callbacks might update component values, which could trigger another
+// call to flush(), the following steps guard against this:
+// 1. During beforeUpdate, any updated components will be added to the
+// dirty_components array and will cause a reentrant call to flush(). Because
+// the flush index is kept outside the function, the reentrant call will pick
+// up where the earlier call left off and go through all dirty components. The
+// current_component value is saved and restored so that the reentrant call will
+// not interfere with the "parent" flush() call.
+// 2. bind:this callbacks cannot trigger new flush() calls.
+// 3. During afterUpdate, any updated components will NOT have their afterUpdate
+//    callback called a second time; the seen_callbacks set, outside the flush()
+//    function, guarantees this behavior.
 const seen_callbacks = new Set();
 let flushidx = 0;  // Do *not* move this inside the flush() function
 export function flush() {