From 85c86de61e46757e96cb290a53c7571f46df18f5 Mon Sep 17 00:00:00 2001
From: Raghunath Prabhakar <82239949+Raghuboi@users.noreply.github.com>
Date: Mon, 11 Aug 2025 11:25:23 -0500
Subject: [PATCH] chore: add jsdoc comments to utils

---
 client/src/utils/jsonUtils.ts  | 10 ++++++++++
 client/src/utils/oauthUtils.ts | 10 ++++++++++
 2 files changed, 20 insertions(+)

diff --git a/client/src/utils/jsonUtils.ts b/client/src/utils/jsonUtils.ts
index 60f5b1d6..08de50ba 100644
--- a/client/src/utils/jsonUtils.ts
+++ b/client/src/utils/jsonUtils.ts
@@ -63,12 +63,22 @@ export type DataType =
   | "array"
   | "null";
 
+/**
+ * Determines the specific data type of a JSON value
+ * @param value The JSON value to analyze
+ * @returns The specific data type including "array" and "null" as distinct types
+ */
 export function getDataType(value: JsonValue): DataType {
   if (Array.isArray(value)) return "array";
   if (value === null) return "null";
   return typeof value;
 }
 
+/**
+ * Attempts to parse a string as JSON, only for objects and arrays
+ * @param str The string to parse
+ * @returns Object with success boolean and either parsed data or original string
+ */
 export function tryParseJson(str: string): {
   success: boolean;
   data: JsonValue;
diff --git a/client/src/utils/oauthUtils.ts b/client/src/utils/oauthUtils.ts
index 83de080b..9b51179c 100644
--- a/client/src/utils/oauthUtils.ts
+++ b/client/src/utils/oauthUtils.ts
@@ -24,6 +24,11 @@ type CallbackParams =
       error_uri: string | null;
     };
 
+/**
+ * Parses OAuth 2.1 callback parameters from a URL search string
+ * @param location The URL search string (e.g., "?code=abc123" or "?error=access_denied")
+ * @returns Parsed callback parameters with success/error information
+ */
 export const parseOAuthCallbackParams = (location: string): CallbackParams => {
   const params = new URLSearchParams(location);
 
@@ -62,6 +67,11 @@ export const generateOAuthState = () => {
   );
 };
 
+/**
+ * Generates a human-readable error description from OAuth callback error parameters
+ * @param params OAuth error callback parameters containing error details
+ * @returns Formatted multiline error message with error code, description, and optional URI
+ */
 export const generateOAuthErrorDescription = (
   params: Extract<CallbackParams, { successful: false }>,
 ): string => {