From e6139a00d4414ba2c1d3e500cdfa67d7e66e655a Mon Sep 17 00:00:00 2001
From: Dimitri POSTOLOV <dmytropostolov@gmail.com>
Date: Sun, 6 Apr 2025 04:52:08 +0200
Subject: [PATCH] Improve TSDoc comments for `useNodesData`, `useReactFlow`,
 `isNode` and `isEdge`

---
 .changeset/afraid-schools-beg.md         |  5 +++++
 packages/react/src/hooks/useNodesData.ts | 10 ++++++----
 packages/react/src/hooks/useReactFlow.ts |  2 --
 packages/react/src/utils/general.ts      | 18 +++++++++++-------
 4 files changed, 22 insertions(+), 13 deletions(-)
 create mode 100644 .changeset/afraid-schools-beg.md

diff --git a/.changeset/afraid-schools-beg.md b/.changeset/afraid-schools-beg.md
new file mode 100644
index 00000000..a908ace5
--- /dev/null
+++ b/.changeset/afraid-schools-beg.md
@@ -0,0 +1,5 @@
+---
+'@xyflow/react': patch
+---
+
+Improve TSDoc comments for `useNodesData`, `useReactFlow`, `isNode` and `isEdge`
diff --git a/packages/react/src/hooks/useNodesData.ts b/packages/react/src/hooks/useNodesData.ts
index 1d2aa37e..6503f405 100644
--- a/packages/react/src/hooks/useNodesData.ts
+++ b/packages/react/src/hooks/useNodesData.ts
@@ -8,11 +8,9 @@ import type { Node } from '../types';
  * This hook lets you subscribe to changes of a specific nodes `data` object.
  *
  * @public
- * @param nodeId - The id (or ids) of the node to get the data from
- * @returns An object (or array of object) with {id, type, data} representing each node
+ * @returns An object (or array of object) with `id`, `type`, `data` representing each node.
  *
  * @example
- *
  *```jsx
  *import { useNodesData } from '@xyflow/react';
  *
@@ -25,9 +23,13 @@ import type { Node } from '../types';
  *```
  */
 export function useNodesData<NodeType extends Node = Node>(
+  /** The id of the node to get the data from. */
   nodeId: string
 ): Pick<NodeType, 'id' | 'type' | 'data'> | null;
-export function useNodesData<NodeType extends Node = Node>(nodeIds: string[]): Pick<NodeType, 'id' | 'type' | 'data'>[];
+export function useNodesData<NodeType extends Node = Node>(
+  /** The ids of the nodes to get the data from. */
+  nodeIds: string[]
+): Pick<NodeType, 'id' | 'type' | 'data'>[];
 // eslint-disable-next-line @typescript-eslint/no-explicit-any
 export function useNodesData(nodeIds: any): any {
   const nodesData = useStore(
diff --git a/packages/react/src/hooks/useReactFlow.ts b/packages/react/src/hooks/useReactFlow.ts
index a02cbb55..2cfc3430 100644
--- a/packages/react/src/hooks/useReactFlow.ts
+++ b/packages/react/src/hooks/useReactFlow.ts
@@ -31,8 +31,6 @@ const selector = (s: ReactFlowState) => !!s.panZoom;
  * This hook returns a ReactFlowInstance that can be used to update nodes and edges, manipulate the viewport, or query the current state of the flow.
  *
  * @public
- * @returns ReactFlowInstance
- *
  * @example
  * ```jsx
  *import { useCallback, useState } from 'react';
diff --git a/packages/react/src/utils/general.ts b/packages/react/src/utils/general.ts
index 52d8eee2..c7c8a503 100644
--- a/packages/react/src/utils/general.ts
+++ b/packages/react/src/utils/general.ts
@@ -4,21 +4,23 @@ import { isNodeBase, isEdgeBase } from '@xyflow/system';
 import type { Edge, Node } from '../types';
 
 /**
- * Test whether an object is useable as an [`Node`](/api-reference/types/node).
+ * Test whether an object is usable as an [`Node`](/api-reference/types/node).
  * In TypeScript this is a type guard that will narrow the type of whatever you pass in to
  * [`Node`](/api-reference/types/node) if it returns `true`.
  *
  * @public
  * @remarks In TypeScript this is a type guard that will narrow the type of whatever you pass in to Node if it returns true
- * @param element - The element to test
- * @returns A boolean indicating whether the element is an Node
+ * @param element - The element to test.
+ * @returns Tests whether the provided value can be used as a `Node`. If you're using TypeScript,
+ * this function acts as a type guard and will narrow the type of the value to `Node` if it returns
+ * `true`.
  *
  * @example
  * ```js
  *import { isNode } from '@xyflow/react';
  *
  *if (isNode(node)) {
- * // ..
+ * // ...
  *}
  *```
  */
@@ -26,21 +28,23 @@ export const isNode = <NodeType extends Node = Node>(element: unknown): element
   isNodeBase<NodeType>(element);
 
 /**
- * Test whether an object is useable as an [`Edge`](/api-reference/types/edge).
+ * Test whether an object is usable as an [`Edge`](/api-reference/types/edge).
  * In TypeScript this is a type guard that will narrow the type of whatever you pass in to
  * [`Edge`](/api-reference/types/edge) if it returns `true`.
  *
  * @public
  * @remarks In TypeScript this is a type guard that will narrow the type of whatever you pass in to Edge if it returns true
  * @param element - The element to test
- * @returns A boolean indicating whether the element is an Edge
+ * @returns Tests whether the provided value can be used as an `Edge`. If you're using TypeScript,
+ * this function acts as a type guard and will narrow the type of the value to `Edge` if it returns
+ * `true`.
  *
  * @example
  * ```js
  *import { isEdge } from '@xyflow/react';
  *
  *if (isEdge(edge)) {
- * // ..
+ * // ...
  *}
  *```
  */