diff --git a/.changeset/light-cherries-greet.md b/.changeset/light-cherries-greet.md
new file mode 100644
index 00000000..299f0555
--- /dev/null
+++ b/.changeset/light-cherries-greet.md
@@ -0,0 +1,5 @@
+---
+'@xyflow/react': patch
+---
+
+fix: improve TSDoc comments for `ReactFlowInstance` and `GeneralHelpers`
diff --git a/packages/react/src/types/instance.ts b/packages/react/src/types/instance.ts
index 7aa615f5..d001486a 100644
--- a/packages/react/src/types/instance.ts
+++ b/packages/react/src/types/instance.ts
@@ -24,13 +24,17 @@ export type GeneralHelpers<NodeType extends Node = Node, EdgeType extends Edge =
    */
   getNodes: () => NodeType[];
   /**
-   * Sets nodes.
+   * Set your nodes array to something else by either overwriting it with a new array or by passing
+   * in a function to update the existing array. If using a function, it is important to make sure a
+   * new array is returned instead of mutating the existing array. Calling this function will
+   * trigger the `onNodesChange` handler in a controlled flow.
    *
    * @param payload - the nodes to set or a function that receives the current nodes and returns the new nodes
    */
   setNodes: (payload: NodeType[] | ((nodes: NodeType[]) => NodeType[])) => void;
   /**
-   * Adds nodes.
+   * Add one or many nodes to your existing nodes array. Calling this function will trigger the
+   * `onNodesChange` handler in a controlled flow.
    *
    * @param payload - the nodes to add
    */
@@ -56,13 +60,17 @@ export type GeneralHelpers<NodeType extends Node = Node, EdgeType extends Edge =
    */
   getEdges: () => EdgeType[];
   /**
-   * Sets edges.
+   * Set your edges array to something else by either overwriting it with a new array or by passing
+   * in a function to update the existing array. If using a function, it is important to make sure a
+   * new array is returned instead of mutating the existing array. Calling this function will
+   * trigger the `onEdgesChange` handler in a controlled flow.
    *
    * @param payload - the edges to set or a function that receives the current edges and returns the new edges
    */
   setEdges: (payload: EdgeType[] | ((edges: EdgeType[]) => EdgeType[])) => void;
   /**
-   * Adds edges.
+   * Add one or many edges to your existing edges array. Calling this function will trigger the
+   * `onEdgesChange` handler in a controlled flow.
    *
    * @param payload - the edges to add
    */
@@ -93,7 +101,8 @@ export type GeneralHelpers<NodeType extends Node = Node, EdgeType extends Edge =
     deletedEdges: Edge[];
   }>;
   /**
-   * Returns all nodes that intersect with the given node or rect.
+   * Find all the nodes currently intersecting with a given node or rectangle. The `partially`
+   * parameter can be set to `true` to include nodes that are only partially intersecting.
    *
    * @param node - the node or rect to check for intersections
    * @param partially - if true, the node is considered to be intersecting if it partially overlaps with the passed node or rect
@@ -107,7 +116,8 @@ export type GeneralHelpers<NodeType extends Node = Node, EdgeType extends Edge =
     nodes?: NodeType[]
   ) => NodeType[];
   /**
-   * Checks if the given node or rect intersects with the passed rect.
+   * Determine if a given node or rectangle is intersecting with another rectangle. The `partially`
+   * parameter can be set to true return `true` even if the node is only partially intersecting.
    *
    * @param node - the node or rect to check for intersections
    * @param area - the rect to check for intersections
@@ -185,7 +195,8 @@ export type GeneralHelpers<NodeType extends Node = Node, EdgeType extends Edge =
    */
   getNodesBounds: (nodes: (NodeType | InternalNode | string)[]) => Rect;
   /**
-   * Gets all connections for a given handle belonging to a specific node.
+   * Get all the connections of a handle belonging to a specific node. The type parameter be either
+   * `'source'` or `'target'`.
    * @deprecated
    * @param type - handle type 'source' or 'target'
    * @param id - the handle id (this is only needed if you have multiple handles of the same type, meaning you have to provide a unique id for each handle)
@@ -241,6 +252,10 @@ export type ReactFlowInstance<NodeType extends Node = Node, EdgeType extends Edg
   NodeType,
   EdgeType
 > &
-  Omit<ViewportHelperFunctions, 'initialized'> & {
+   ViewportHelperFunctions & {
+  /**
+   * React Flow needs to mount the viewport to the DOM and initialize its zoom and pan behavior.
+   * This property tells you when viewport is initialized.
+   */
     viewportInitialized: boolean;
   };