From d536abea9240bad7f5c1064efc0a4713ebef87d1 Mon Sep 17 00:00:00 2001
From: Dimitri POSTOLOV <dmytropostolov@gmail.com>
Date: Sat, 5 Apr 2025 17:37:43 +0200
Subject: [PATCH] Improve TSDoc comments for `useViewport`,
 `useUpdateNodeInternals`, `useOnSelectionChange`, `useNodesInitialized` hooks
 and `UseOnSelectionChangeOptions`, `UseNodesInitializedOptions` types

---
 .changeset/beige-apes-repair.md                    | 5 +++++
 packages/react/src/hooks/useNodesInitialized.ts    | 5 +++--
 packages/react/src/hooks/useOnSelectionChange.ts   | 3 +--
 packages/react/src/hooks/useUpdateNodeInternals.ts | 9 +++++----
 packages/react/src/hooks/useViewport.ts            | 6 +++---
 5 files changed, 17 insertions(+), 11 deletions(-)
 create mode 100644 .changeset/beige-apes-repair.md

diff --git a/.changeset/beige-apes-repair.md b/.changeset/beige-apes-repair.md
new file mode 100644
index 00000000..252866a3
--- /dev/null
+++ b/.changeset/beige-apes-repair.md
@@ -0,0 +1,5 @@
+---
+'@xyflow/react': patch
+---
+
+Improve TSDoc comments for `useViewport`, `useUpdateNodeInternals`, `useOnSelectionChange`, `useNodesInitialized` hooks and `UseOnSelectionChangeOptions`, `UseNodesInitializedOptions` types
diff --git a/packages/react/src/hooks/useNodesInitialized.ts b/packages/react/src/hooks/useNodesInitialized.ts
index 38f15a60..a44ab658 100644
--- a/packages/react/src/hooks/useNodesInitialized.ts
+++ b/packages/react/src/hooks/useNodesInitialized.ts
@@ -4,6 +4,7 @@ import { useStore } from './useStore';
 import type { ReactFlowState } from '../types';
 
 export type UseNodesInitializedOptions = {
+  /** @default false */
   includeHiddenNodes?: boolean;
 };
 
@@ -29,8 +30,8 @@ const selector = (options: UseNodesInitializedOptions) => (s: ReactFlowState) =>
  *`false` and then `true` again once the node has been measured.
  *
  * @public
- * @param options.includeHiddenNodes - defaults to false
- * @returns boolean indicating whether all nodes are initialized
+ * @returns Whether or not the nodes have been initialized by the `<ReactFlow />` component and
+ * given a width and height.
  *
  * @example
  * ```jsx
diff --git a/packages/react/src/hooks/useOnSelectionChange.ts b/packages/react/src/hooks/useOnSelectionChange.ts
index 17232895..feff9fe3 100644
--- a/packages/react/src/hooks/useOnSelectionChange.ts
+++ b/packages/react/src/hooks/useOnSelectionChange.ts
@@ -4,6 +4,7 @@ import { useStoreApi } from './useStore';
 import type { OnSelectionChangeFunc, Node, Edge } from '../types';
 
 export type UseOnSelectionChangeOptions<NodeType extends Node = Node, EdgeType extends Edge = Edge> = {
+  /** The handler to register. */
   onChange: OnSelectionChangeFunc<NodeType, EdgeType>;
 };
 
@@ -13,8 +14,6 @@ export type UseOnSelectionChangeOptions<NodeType extends Node = Node, EdgeType e
  *_either_ nodes or edges changes.
  *
  * @public
- * @param params.onChange - The handler to register
- *
  * @example
  * ```jsx
  *import { useState } from 'react';
diff --git a/packages/react/src/hooks/useUpdateNodeInternals.ts b/packages/react/src/hooks/useUpdateNodeInternals.ts
index 4463ed2a..55765b80 100644
--- a/packages/react/src/hooks/useUpdateNodeInternals.ts
+++ b/packages/react/src/hooks/useUpdateNodeInternals.ts
@@ -5,12 +5,13 @@ import { useStoreApi } from '../hooks/useStore';
 
 /**
  * When you programmatically add or remove handles to a node or update a node's
- *handle position, you need to let React Flow know about it using this hook. This
- *will update the internal dimensions of the node and properly reposition handles
- *on the canvas if necessary.
+ * handle position, you need to let React Flow know about it using this hook. This
+ * will update the internal dimensions of the node and properly reposition handles
+ * on the canvas if necessary.
  *
  * @public
- * @returns function for updating node internals
+ * @returns Use this function to tell React Flow to update the internal state of one or more nodes
+ * that you have changed programmatically.
  *
  * @example
  * ```jsx
diff --git a/packages/react/src/hooks/useViewport.ts b/packages/react/src/hooks/useViewport.ts
index a892e5a8..1528fbf5 100644
--- a/packages/react/src/hooks/useViewport.ts
+++ b/packages/react/src/hooks/useViewport.ts
@@ -12,11 +12,11 @@ const viewportSelector = (state: ReactFlowState) => ({
 
 /**
  * The `useViewport` hook is a convenient way to read the current state of the
- *{@link Viewport} in a component. Components that use this hook
- *will re-render **whenever the viewport changes**.
+ * {@link Viewport} in a component. Components that use this hook
+ * will re-render **whenever the viewport changes**.
  *
  * @public
- * @returns The current viewport
+ * @returns The current viewport.
  *
  * @example
  *