Merge pull request #7532 from QwikDev/v2-more-explanations

chore: more functions explanations

Author: Varixo

packages/qwik/src/core/client/dom-container.ts

@@ -375,6 +375,23 @@ export class DomContainer extends _SharedContainer implements IClientContainer {
     this.$serverData$ = { containerAttributes };
   }
 
+  /**
+   * Schedule the initial QRLs to be resolved.
+   *
+   * Schedules the QRLs that are defined in the state data as `PreloadQRL`.
+   *
+   * This is done because when computed and custom serializer QRLs are called they need QRL to work.
+   * If the QRL is not resolved at this point, it will be resolved by throwing a promise and
+   * rerunning the whole wrapping function again. We want to avoid that, because it means that the
+   * function can execute twice.
+   *
+   * ```ts
+   * useVisibleTask$(() => {
+   *   runHeavyLogic(); // This will be called again if the QRL of `computedOrCustomSerializer` is not resolved.
+   *   console.log(computedOrCustomSerializer.value); // Throw a promise if QRL not resolved and execute visible task again.
+   * });
+   * ```
+   */
   private $scheduleInitialQRLs$(): void {
     if (this.$initialQRLsIndexes$) {
       for (const index of this.$initialQRLsIndexes$) {

packages/qwik/src/core/shared/shared-serialization.ts

@@ -1570,7 +1570,11 @@ export function _createDeserializeContainer(
 }
 
 /**
- * Preprocess the state data to replace RootRef with the actual object.
+ * Preprocess the state data to:
+ *
+ * - Replace RootRef with the actual object
+ * - Create a map for forward refs
+ * - Create an array of indexes for initial QRLs
  *
  * Before:
  *