Add additional comments on Context, Frames, and render

Author: kitten

src/index.js

@@ -23,6 +23,11 @@ const {
 
 let prevDispatcher = ReactCurrentDispatcher.current
 
+/** visitChildren walks all elements (depth-first) and while it walks the
+    element tree some components will suspend and put a `Frame` onto
+    the queue. Hence we recursively look at suspended components in
+    this queue, wait for their promises to resolve, and continue
+    calling visitChildren on their children. */
 const flushFrames = (queue: Frame[], visitor: Visitor): Promise<void> => {
   if (queue.length === 0) {
     return Promise.resolve()
@@ -35,6 +40,9 @@ const flushFrames = (queue: Frame[], visitor: Visitor): Promise<void> => {
     ReactCurrentDispatcher.current = Dispatcher
 
     let children = []
+
+    // Update the component after we've suspended to rerender it,
+    // at which point we'll actually get its children
     if (frame.kind === 'frame.class') {
       children = getChildrenArray(updateClassComponent(queue, frame))
     } else if (frame.kind === 'frame.hooks') {
@@ -43,6 +51,8 @@ const flushFrames = (queue: Frame[], visitor: Visitor): Promise<void> => {
       children = getChildrenArray(updateLazyComponent(queue, frame))
     }
 
+    // Now continue walking the previously suspended component's
+    // children (which might also suspend)
     visitChildren(children, queue, visitor)
     ReactCurrentDispatcher.current = prevDispatcher
 
@@ -56,12 +66,19 @@ const renderPrepass = (element: Node, visitor?: Visitor): Promise<void> => {
   const queue: Frame[] = []
   let fn = visitor !== undefined ? visitor : defaultVisitor
 
+  // Context state is kept globally and is modified in-place.
+  // Before we start walking the element tree we need to reset
+  // its current state
   setCurrentContextMap({})
   setCurrentContextStore(new Map())
 
   try {
+    // The "Dispatcher" is what handles hook calls and
+    // a React internal that needs to be set to our
+    // dispatcher and reset after we're done
     prevDispatcher = ReactCurrentDispatcher.current
     ReactCurrentDispatcher.current = Dispatcher
+
     visitChildren(getChildrenArray(element), queue, fn)
   } catch (error) {
     return Promise.reject(error)

src/internals/context.js

@@ -7,7 +7,7 @@ import type {
   ContextStore
 } from '../types'
 
-/* The context is kept as a Map from a Context value to the current
+/** The context is kept as a Map from a Context value to the current
    value on the React element tree.
    The legacy context is kept as a simple object.
    When the tree is being walked modifications are made by assigning

src/render/index.js

@@ -1,5 +1,13 @@
 // @flow
 
+/** Every type of component here can suspend itself.
+    This means it pushes a `Frame` to the queue.
+    Components are first mounted in visitor.js,
+    and if they have suspended after their promise
+    resolves `update` is called instead for them,
+    which preserves their previous mounted state
+    and rerenders the component. */
+
 export {
   mount as mountLazyComponent,
   update as updateLazyComponent

src/visitor.js

@@ -148,13 +148,18 @@ export const visitElement = (
   }
 }
 
+/** The context (legacy and createContext are separate) are kept
+    as global state. As we're walking the tree depth-first, we
+    simply overwrite it with new values. This is recursive and
+    as we walk back upwards (after visitChildren) we restore
+    the value that we have previously overwritten. */
 const visitChild = (
   child: AbstractElement,
   queue: Frame[],
   visitor: Visitor
 ) => {
   const children = visitElement(child, queue, visitor)
-  // Flush the context changes
+  // Flush changes (if any) that have been made to the context
   const prevMap = flushPrevContextMap()
   const prevStore = flushPrevContextStore()