From 7c1ed915fbaced22e01f57016226ac2602c1319e Mon Sep 17 00:00:00 2001
From: James Jarvis <jjarvisp@amazon.com>
Date: Mon, 19 Aug 2024 09:38:53 -0400
Subject: [PATCH] docs: update tsdocs to reduce gaps (#13700)

* Update TSDoc Comments
---
 packages/api-rest/src/errors/CanceledError.ts        | 3 +++
 packages/api/src/API.ts                              | 3 +++
 packages/core/src/singleton/Auth/utils/index.ts      | 6 ++++++
 packages/core/src/singleton/apis/fetchAuthSession.ts | 9 +++++++++
 packages/storage/src/errors/CanceledError.ts         | 2 ++
 5 files changed, 23 insertions(+)

diff --git a/packages/api-rest/src/errors/CanceledError.ts b/packages/api-rest/src/errors/CanceledError.ts
index ce4082212e0..67278d62a7c 100644
--- a/packages/api-rest/src/errors/CanceledError.ts
+++ b/packages/api-rest/src/errors/CanceledError.ts
@@ -29,6 +29,9 @@ export class CanceledError extends RestApiError {
  *
  * @note This function works **ONLY** for errors thrown by REST API. For GraphQL APIs, use `client.isCancelError(error)`
  *   instead. `client` is generated from  `generateClient()` API from `aws-amplify/api`.
+ *
+ * @param {unknown} error The unknown exception to be checked.
+ * @returns - A boolean indicating if the error was from an upload cancellation
  */
 export const isCancelError = (error: unknown): error is CanceledError =>
 	!!error && error instanceof CanceledError;
diff --git a/packages/api/src/API.ts b/packages/api/src/API.ts
index db0559e4477..8aee0fc3334 100644
--- a/packages/api/src/API.ts
+++ b/packages/api/src/API.ts
@@ -6,6 +6,9 @@ import { Amplify } from '@aws-amplify/core';
 
 /**
  * Generates an API client that can work with models or raw GraphQL
+ *
+ * @returns {@link V6Client}
+ * @throws {@link Error} - Throws error when client cannot be generated due to configuration issues.
  */
 export function generateClient<T extends Record<any, any> = never>(
 	options: CommonPublicClientOptions = {},
diff --git a/packages/core/src/singleton/Auth/utils/index.ts b/packages/core/src/singleton/Auth/utils/index.ts
index c710e64a1ee..496d28db68d 100644
--- a/packages/core/src/singleton/Auth/utils/index.ts
+++ b/packages/core/src/singleton/Auth/utils/index.ts
@@ -66,6 +66,12 @@ export function assertIdentityPoolIdConfig(
 	);
 }
 
+/**
+ * Decodes payload of JWT token
+ *
+ * @param {String} token A string representing a token to be decoded
+ * @throws {@link Error} - Throws error when token is invalid or payload malformed.
+ */
 export function decodeJWT(token: string): JWT {
 	const tokenParts = token.split('.');
 
diff --git a/packages/core/src/singleton/apis/fetchAuthSession.ts b/packages/core/src/singleton/apis/fetchAuthSession.ts
index f7e1248ae54..1e7d4aa5f04 100644
--- a/packages/core/src/singleton/apis/fetchAuthSession.ts
+++ b/packages/core/src/singleton/apis/fetchAuthSession.ts
@@ -6,6 +6,15 @@ import { AuthSession, FetchAuthSessionOptions } from '../Auth/types';
 
 import { fetchAuthSession as fetchAuthSessionInternal } from './internal/fetchAuthSession';
 
+/**
+ * Fetch the auth session including the tokens and credentials if they are available. By default it
+ * does not refresh the auth tokens or credentials if they are loaded in storage already. You can force a refresh
+ * with `{ forceRefresh: true }` input.
+ *
+ * @param options - Options configuring the fetch behavior.
+ * @throws {@link AuthError} - Throws error when session information cannot be refreshed.
+ * @returns Promise<AuthSession>
+ */
 export const fetchAuthSession = (
 	options?: FetchAuthSessionOptions,
 ): Promise<AuthSession> => {
diff --git a/packages/storage/src/errors/CanceledError.ts b/packages/storage/src/errors/CanceledError.ts
index 9388653432a..da069ab1f13 100644
--- a/packages/storage/src/errors/CanceledError.ts
+++ b/packages/storage/src/errors/CanceledError.ts
@@ -28,6 +28,8 @@ export class CanceledError extends StorageError {
 /**
  * Check if an error is caused by user calling `cancel()` on a upload/download task. If an overwriting error is
  * supplied to `task.cancel(errorOverwrite)`, this function will return `false`.
+ * @param {unknown} error The unknown exception to be checked.
+ * @returns - A boolean indicating if the error was from an upload cancellation
  */
 export const isCancelError = (error: unknown): error is CanceledError =>
 	!!error && error instanceof CanceledError;