From 8ee3fb64ed805b405c7c6c9476f8ba8f3a4a76c8 Mon Sep 17 00:00:00 2001
From: Peter <p.korcsak@googlemail.com>
Date: Tue, 5 Dec 2023 13:48:49 +0100
Subject: [PATCH] Added TSDoc for util functions in svelte

---
 packages/svelte/src/lib/utils/index.ts | 58 ++++++++++++++++++++++++++
 1 file changed, 58 insertions(+)

diff --git a/packages/svelte/src/lib/utils/index.ts b/packages/svelte/src/lib/utils/index.ts
index 23b29448..a44f471d 100644
--- a/packages/svelte/src/lib/utils/index.ts
+++ b/packages/svelte/src/lib/utils/index.ts
@@ -10,10 +10,68 @@ import {
 
 import type { Edge, Node } from '$lib/types';
 
+/**
+ * Test whether an object is useable as a Node
+ * @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
+ */
 export const isNode = isNodeBase<Node, Edge>;
+
+/**
+ * Test whether an object is useable as an Edge
+ * @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
+ */
 export const isEdge = isEdgeBase<Node, Edge>;
+
+/**
+ * Pass in a node, and get connected nodes where edge.source === node.id
+ * @public
+ * @param node - The node to get the connected nodes from
+ * @param nodes - The array of all nodes
+ * @param edges - The array of all edges
+ * @returns An array of nodes that are connected over eges where the source is the given node
+ */
 export const getOutgoers = getOutgoersBase<Node, Edge>;
+
+/**
+ * Pass in a node, and get connected nodes where edge.target === node.id
+ * @public
+ * @param node - The node to get the connected nodes from
+ * @param nodes - The array of all nodes
+ * @param edges - The array of all edges
+ * @returns An array of nodes that are connected over eges where the target is the given node
+ */
 export const getIncomers = getIncomersBase<Node, Edge>;
+
+/**
+ * This util is a convenience function to add a new Edge to an array of edges
+ * @remarks It also performs some validation to make sure you don't add an invalid edge or duplicate an existing one.
+ * @public
+ * @param edgeParams - Either an Edge or a Connection you want to add
+ * @param edges -  The array of all current edges
+ * @returns A new array of edges with the new edge added
+ */
 export const addEdge = addEdgeBase<Edge>;
+
+/**
+ * A handy utility to update an existing Edge with new properties
+ * @param oldEdge - The edge you want to update
+ * @param newConnection - The new connection you want to update the edge with
+ * @param edges - The array of all current edges
+ * @param options.shouldReplaceId - should the id of the old edge be replaced with the new connection id
+ * @returns the updated edges array
+ */
 export const updateEdge = updateEdgeBase<Edge>;
+
+/**
+ * Get all connecting edges for a given set of nodes
+ * @param nodes - Nodes you want to get the connected edges for
+ * @param edges - All edges
+ * @returns Array of edges that connect any of the given nodes with each other
+ */
 export const getConnectedEdges = getConnectedEdgesBase<Node, Edge>;