diff --git a/.changeset/heavy-mirrors-draw.md b/.changeset/heavy-mirrors-draw.md
new file mode 100644
index 00000000..ccb9ae31
--- /dev/null
+++ b/.changeset/heavy-mirrors-draw.md
@@ -0,0 +1,5 @@
+---
+'@xyflow/react': patch
+---
+
+Improve TSDoc comments for `useNodesState` and `useEdgesState` hook
diff --git a/packages/react/src/hooks/useNodesEdgesState.ts b/packages/react/src/hooks/useNodesEdgesState.ts
index b5919e5e..21d9d108 100644
--- a/packages/react/src/hooks/useNodesEdgesState.ts
+++ b/packages/react/src/hooks/useNodesEdgesState.ts
@@ -9,8 +9,16 @@ import type { Node, Edge, OnNodesChange, OnEdgesChange } from '../types';
  * like React's `useState` hook with an additional helper callback.
  *
  * @public
- * @param initialNodes
- * @returns an array [nodes, setNodes, onNodesChange]
+ * @returns
+ * - `nodes`: The current array of nodes. You might pass this directly to the `nodes` prop of your
+ * `<ReactFlow />` component, or you may want to manipulate it first to perform some layouting,
+ * for example.
+ * - `setNodes`: A function that you can use to update the nodes. You can pass it a new array of
+ * nodes or a callback that receives the current array of nodes and returns a new array of nodes.
+ * This is the same as the second element of the tuple returned by React's `useState` hook.
+ * - `onNodesChange`: A handy callback that can take an array of `NodeChanges` and update the nodes
+ * state accordingly. You'll typically pass this directly to the `onNodesChange` prop of your
+ * `<ReactFlow />` component.
  * @example
  *
  *```tsx
@@ -42,7 +50,12 @@ import type { Node, Edge, OnNodesChange, OnEdgesChange } from '../types';
  */
 export function useNodesState<NodeType extends Node>(
   initialNodes: NodeType[]
-): [NodeType[], Dispatch<SetStateAction<NodeType[]>>, OnNodesChange<NodeType>] {
+): [
+  //
+  nodes: NodeType[],
+  setNodes: Dispatch<SetStateAction<NodeType[]>>,
+  onNodesChange: OnNodesChange<NodeType>
+] {
   const [nodes, setNodes] = useState(initialNodes);
   const onNodesChange: OnNodesChange<NodeType> = useCallback(
     (changes) => setNodes((nds) => applyNodeChanges(changes, nds)),
@@ -58,8 +71,18 @@ export function useNodesState<NodeType extends Node>(
  * like React's `useState` hook with an additional helper callback.
  *
  * @public
- * @param initialEdges
- * @returns an array [edges, setEdges, onEdgesChange]
+ * @returns
+ * - `edges`: The current array of edges. You might pass this directly to the `edges` prop of your
+ * `<ReactFlow />` component, or you may want to manipulate it first to perform some layouting,
+ * for example.
+ *
+ * - `setEdges`: A function that you can use to update the edges. You can pass it a new array of
+ * edges or a callback that receives the current array of edges and returns a new array of edges.
+ * This is the same as the second element of the tuple returned by React's `useState` hook.
+ *
+ * - `onEdgesChange`: A handy callback that can take an array of `EdgeChanges` and update the edges
+ * state accordingly. You'll typically pass this directly to the `onEdgesChange` prop of your
+ * `<ReactFlow />` component.
  * @example
  *
  *```tsx
@@ -91,7 +114,12 @@ export function useNodesState<NodeType extends Node>(
  */
 export function useEdgesState<EdgeType extends Edge = Edge>(
   initialEdges: EdgeType[]
-): [EdgeType[], Dispatch<SetStateAction<EdgeType[]>>, OnEdgesChange<EdgeType>] {
+): [
+  //
+  edges: EdgeType[],
+  setEdges: Dispatch<SetStateAction<EdgeType[]>>,
+  onEdgesChange: OnEdgesChange<EdgeType>
+] {
   const [edges, setEdges] = useState(initialEdges);
   const onEdgesChange: OnEdgesChange<EdgeType> = useCallback(
     (changes) => setEdges((eds) => applyEdgeChanges(changes, eds)),