[lexical-utils] Documentation Update: describe $reverseDfs instead of $reverseDfsIterator

[luantaraschi]

Description

$reverseDfs carries the JSDoc block of $reverseDfsIterator, copied word for word, so three of its statements describe a different function.

/**
 * $dfs iterator (right to left). Tree traversal is done on the fly as new values are requested with O(1) memory.
 * ...
 * @returns An iterator, each yielded value is a DFSNode. It will always return at least 1 node (the start node).
 */
export function $reverseDfs(
  startNode?: LexicalNode,
  endNode?: LexicalNode,
): DFSNode[] {
  return Array.from($reverseDfsIterator(startNode, endNode));
}

It is not an iterator, it returns DFSNode[]. Traversal is not done on the fly, Array.from runs it to completion before returning. Memory is not O(1) for the same reason. The @returns line then tells the reader to expect an iterator.

$dfs is the same shape, Array.from over its iterator, and its doc gets this right: "It will then return all the nodes found in the search in an array of objects". $reverseDfs now says the same thing.

Two things were also missing that both $dfs and $dfsIterator document and that apply here equally:

• the children-only spine, with the pointer to $reverseDfsWithSlots, which exists and is the slot-aware counterpart
• that an ElementNode passed as endNode stops the traversal before its children

No behavior change, and the wording follows $dfs so the pair reads consistently.

Test plan

Before

// hovering $reverseDfs in an editor
(startNode?: LexicalNode, endNode?: LexicalNode) => DFSNode[]
// "$dfs iterator (right to left) ... O(1) memory"
// "@returns An iterator, each yielded value is a DFSNode"

After

(startNode?: LexicalNode, endNode?: LexicalNode) => DFSNode[]
// "Right-to-left mirror of $dfs. It returns all the nodes found in the search in an array of objects."
// "@returns An array of objects of all the nodes found by the search, including their depth into the tree."

pnpm run prettier and pnpm run tsc are clean. The lexical-utils unit suite passes, 225 tests across 15 files.

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
lexical	Ready	Preview	Aug 7, 2026 6:40pm
lexical-playground	Ready	Preview	Aug 7, 2026 6:40pm

[Copilot]

Copilot was unable to review this pull request because the user who requested the review has reached their quota limit.