Document MountItemDispatcher (#41114)

Summary:
Pull Request resolved: #41114

changelog: [internal]

MountItemDispatcher integrates with FabricUIManager in a non-obvious ways. This diff documents some of that.

Reviewed By: NickGerleman

Differential Revision: D50494929

fbshipit-source-id: ed3c1748765ca4590035be20f045ecfb14af86c2

packages/react-native/ReactAndroid/src/main/java/com/facebook/react/fabric/FabricUIManager.java

@@ -1294,6 +1294,11 @@ public void doFrameGuarded(long frameTimeNanos) {
       }
 
       try {
+        // First, execute as many pre mount items as we can within frameTimeNanos time.
+        // If not all pre mount items were executed, following may happen:
+        //   1. In case there are view commands or mount items in MountItemDispatcher: execute
+        //   remaining pre mount items.
+        //   2. In case there are no view commands or mount items, wait until next frame.
         mMountItemDispatcher.dispatchPreMountItems(frameTimeNanos);
         mMountItemDispatcher.tryDispatchMountItems();
       } catch (Exception ex) {

packages/react-native/ReactAndroid/src/main/java/com/facebook/react/fabric/mounting/MountItemDispatcher.java

@@ -161,9 +161,17 @@ public void dispatchMountItems(Queue<MountItem> mountItems) {
     }
   }
 
+  /*
+   * Executes view commands, pre mount items and mount items in the respective order:
+   * 1. View commands.
+   * 2. Pre mount items.
+   * 3. Regular mount items.
+   *
+   * Does nothing if `viewCommandMountItemsToDispatch` and `mountItemsToDispatch` are empty.
+   * Nothing should call this directly except for `tryDispatchMountItems`.
+   */
   @UiThread
   @ThreadConfined(UI)
-  /** Nothing should call this directly except for `tryDispatchMountItems`. */
   private boolean dispatchMountItems() {
     if (mReDispatchCounter == 0) {
       mBatchedExecutionTime = 0;
@@ -296,6 +304,12 @@ private boolean dispatchMountItems() {
     return true;
   }
 
+  /*
+   * Executes pre mount items. Pre mount items are operations that can be executed before the mount items come. For example view preallocation.
+   * This is a performance optimisation to do as much work ahead of time as possible.
+   *
+   * `tryDispatchMountItems` will also execute pre mount items, but only if there are mount items to be executed.
+   */
   @UiThread
   @ThreadConfined(UI)
   public void dispatchPreMountItems(long frameTimeNanos) {