📝 Add docstrings to `edison/refactor/hydrationNode`

Docstrings generation was requested by @edison1105.

* https://github.com/vuejs/core/pull/14340#issuecomment-3770870707

The following files were modified:

* `packages/compiler-vapor/src/generators/operation.ts`
* `packages/compiler-vapor/src/generators/template.ts`
* `packages/compiler-vapor/src/transforms/transformChildren.ts`
* `packages/runtime-vapor/src/dom/hydration.ts`
* `packages/runtime-vapor/src/dom/node.ts`
* `packages/runtime-vapor/src/insertionState.ts`

packages/compiler-vapor/src/generators/operation.ts

@@ -162,6 +162,17 @@ export function genEffect(
   return frag
 }
 
+/**
+ * Generate the code fragments that set up insertion state for a block's parent during code generation.
+ *
+ * @param operation - Insertion state descriptor containing:
+ *   - parent: the parent node id
+ *   - anchor: the anchor node id or -1 for prepend, or undefined
+ *   - logicalIndex: optional logical index used for append scenarios
+ *   - append: whether the insertion is an append
+ *   - last: whether this is the last insertion in the block
+ * @returns An array of CodeFragment containing a newline and a call to the `setInsertionState` helper with:
+ *   the parent node id, the runtime anchor (or `null`/`0`/`undefined` as appropriate), the stringified logicalIndex when provided, and `'true'` when `last` is set.
 function genInsertionState(
   operation: InsertionStateTypes,
   context: CodegenContext,
@@ -184,4 +195,4 @@ function genInsertionState(
       last && 'true',
     ),
   ]
-}
+}

packages/compiler-vapor/src/generators/template.ts

@@ -55,6 +55,24 @@ export function genSelf(
   return frag
 }
 
+/**
+ * Generate code fragments to access and initialize all children of a dynamic node.
+ *
+ * Iterates dynamic.children and emits fragments that:
+ * - skip or adjust indexing for NON_TEMPLATE children,
+ * - resolve a child's reference id (anchor or id) when REFERENCED (and possibly INSERT),
+ * - create a temporary variable (or use `n{id}`) that references the child node using
+ *   helpers such as `child`, `next`, or `nthChild` with the child's computed element and logical indices,
+ * - inline generation for child nodes that require their own dynamic setup,
+ * - emit directive code for referenced element ids,
+ * - recurse into children to generate nested child handling.
+ *
+ * @param dynamic - IR dynamic node containing children and related metadata used to determine indexing and reference behavior
+ * @param context - CodegenContext providing helper lookups and naming utilities
+ * @param pushBlock - Callback used to append code fragment pieces (e.g., helper call expressions) to the output stream
+ * @param from - Expression that refers to the parent node from which children are accessed; defaults to `n${dynamic.id}`
+ * @returns An array of CodeFragment objects representing the generated code for all processed children
+ */
 export function genChildren(
   dynamic: IRDynamicInfo,
   context: CodegenContext,
@@ -146,4 +164,4 @@ export function genChildren(
   }
 
   return frag
-}
+}

packages/compiler-vapor/src/transforms/transformChildren.ts

@@ -58,6 +58,17 @@ export const transformChildren: NodeTransform = (node, context) => {
   }
 }
 
+/**
+ * Analyze a fragment-like element's dynamic children, assign logical indices for SSR hydration, and register insertion points or placeholder templates.
+ *
+ * Processes the array in `context.dynamic.children`, grouping INSERT dynamics and handling non-template children so that hydration indices and insertion operations are produced. As a result it may:
+ * - set `logicalIndex`, `anchor`, `flags`, and `operation` fields on dynamic child entries;
+ * - update `context.childrenTemplate` with placeholder templates where needed;
+ * - register insertion operations/anchors via the transform `context`.
+ * It also marks the final insertion operation as the last insertion when applicable.
+ *
+ * @param context - The element transform context whose dynamic children and templates will be mutated and whose operations/ids may be registered
+ */
 function processDynamicChildren(context: TransformContext<ElementNode>) {
   let prevDynamics: IRDynamicInfo[] = []
   let staticCount = 0
@@ -112,6 +123,18 @@ function processDynamicChildren(context: TransformContext<ElementNode>) {
   }
 }
 
+/**
+ * Apply insertion transformations for a group of dynamic children within a fragment-like transform context.
+ *
+ * Mutates each dynamic item by either registering an `INSERT_NODE` operation (for items with a `template`)
+ * or updating the child's block operation fields (`parent`, `anchor`, `logicalIndex`, `append`) so the
+ * operation is correctly anchored and ordered for SSR hydration and runtime insertion.
+ *
+ * @param dynamics - The dynamic children to register or update.
+ * @param context - The transform context used to register operations and obtain the parent reference.
+ * @param anchor - The numerical anchor index to use for anchoring insertions; special values (e.g. -1) indicate prepend semantics.
+ * @param append - When true, treat the insertion as an append (do not set an explicit anchor on generated insert operations).
+ */
 function registerInsertion(
   dynamics: IRDynamicInfo[],
   context: TransformContext,
@@ -136,4 +159,4 @@ function registerInsertion(
       child.operation.append = append
     }
   }
-}
+}

packages/runtime-vapor/src/dom/hydration.ts

@@ -39,6 +39,14 @@ export function runWithoutHydration(fn: () => any): any {
 
 let isOptimized = false
 
+/**
+ * Run a function within a hydration-enabled environment, performing one-time optimization and ensuring hydration state is set up and restored.
+ *
+ * @param fn - The primary operation to execute while hydration is active; its return value is propagated.
+ * @param setup - Routine executed before `fn` to prepare hydration-related state.
+ * @param cleanup - Routine executed after `fn` to finalize or clear hydration-related state.
+ * @returns The value returned by `fn`.
+ */
 function performHydration<T>(
   fn: () => T,
   setup: () => void,
@@ -155,6 +163,11 @@ export function locateNextNode(node: Node): Node | null {
       : _next(node)
 }
 
+/**
+ * Sets the current hydration node from insertionIndex, insertionParent, or the existing currentHydrationNode and resets insertion state.
+ *
+ * If insertionIndex is defined, selects the node via logical index lookup; otherwise uses insertionParent.firstChild when insertionParent exists, or falls back to the previously tracked currentHydrationNode. In development builds, throws an error if no node can be determined.
+ */
 function locateHydrationNodeImpl(): void {
   let node: Node | null
 
@@ -276,4 +289,4 @@ export function removeFragmentNodes(node: Node, endAnchor?: Node): void {
       break
     }
   }
-}
+}

packages/runtime-vapor/src/dom/node.ts

@@ -137,6 +137,17 @@ export function disableHydrationNodeLookup(): void {
   nthChild.impl = _nthChild
 }
 
+/**
+ * Locate the Node corresponding to a zero-based logical child index within an insertion parent.
+ *
+ * Searches from a cached starting position on `parent` when available, updates the parent's cache
+ * to the found child, and sets the child's cached logical index. When a fragment start comment (`'['`)
+ * is encountered, the search skips the entire fragment to the node after its matching end anchor.
+ *
+ * @param parent - The insertion parent whose logical children are being searched
+ * @param logicalIndex - The zero-based logical index of the desired child
+ * @returns The Node at the given logical index, or `null` if no such node exists
+ */
 export function locateChildByLogicalIndex(
   parent: InsertionParent,
   logicalIndex: number,
@@ -169,4 +180,4 @@ export function locateChildByLogicalIndex(
   }
 
   return null
-}
+}

packages/runtime-vapor/src/insertionState.ts

@@ -22,9 +22,12 @@ export let insertionIndex: number | undefined
 export let isLastInsertion: boolean | undefined
 
 /**
- * This function is called before a block type that requires insertion
- * (component, slot outlet, if, for) is created. The state is used for actual
- * insertion on client-side render, and used for node adoption during hydration.
+ * Establishes global insertion state used for subsequent DOM insertion or node adoption during hydration.
+ *
+ * @param parent - The parent node under which new nodes will be inserted; may receive a cached first-child in `parent.$fc`.
+ * @param anchor - A DOM node to use as the insertion anchor, `0` to indicate the position before the first child, or `null`/`undefined` for no anchor.
+ * @param logicalIndex - Optional logical index used during hydration to locate where nodes should be adopted.
+ * @param last - Optional flag indicating this insertion is the last within its containing sequence.
  */
 export function setInsertionState(
   parent: ParentNode & { $fc?: Node | null },
@@ -51,10 +54,15 @@ export function setInsertionState(
   }
 }
 
+/**
+ * Clear any active insertion state used for client-side insertion and hydration.
+ *
+ * Resets `insertionParent`, `insertionAnchor`, `insertionIndex`, and `isLastInsertion` to `undefined`.
+ */
 export function resetInsertionState(): void {
   insertionParent =
     insertionAnchor =
     insertionIndex =
     isLastInsertion =
       undefined
-}
+}