docs: improve documentation of request state

Author: michaelschoenbaechler

src/app/shared/models/request-state.model.ts

@@ -14,6 +14,15 @@ export interface RequestState<T = unknown> {
   data?: T;
 }
 
+/**
+ * Creates a new RequestState with default values.
+ * - loading: false
+ * - success: false
+ * - error: null
+ * @template T Type of the request payload
+ * @param initialData Optional initial data to attach
+ * @returns Fresh request state instance
+ */
 export function createDefaultRequestState<T>(initialData?: T): RequestState<T> {
   return {
     loading: false,
@@ -23,6 +32,15 @@ export function createDefaultRequestState<T>(initialData?: T): RequestState<T> {
   };
 }
 
+/**
+ * Marks the request as loading and clears previous success/error flags.
+ * Optionally primes the state with new data (useful for optimistic UI updates).
+ * Note: data is only set when a truthy value is provided.
+ * @template T
+ * @param req Previous request state
+ * @param data Optional data to set while loading
+ * @returns Updated request state in loading state
+ */
 export function onRequestLoad<T>(
   req: RequestState<T>,
   data?: T
@@ -36,6 +54,14 @@ export function onRequestLoad<T>(
   };
 }
 
+/**
+ * Marks the request as successfully completed with the given payload.
+ * Clears error and stops loading.
+ * @template T
+ * @param req Previous request state
+ * @param data Resulting data for the request
+ * @returns Updated request state in success state
+ */
 export function onRequestSuccess<T>(
   req: RequestState<T>,
   data?: T
@@ -49,6 +75,14 @@ export function onRequestSuccess<T>(
   };
 }
 
+/**
+ * Marks the request as failed with the provided error information.
+ * Clears success and stops loading. Falls back to a default error when none is provided.
+ * @template T
+ * @param req Previous request state
+ * @param errorInfo Structured error details
+ * @returns Updated request state in error state
+ */
 export function onRequestError<T>(
   req: RequestState<T>,
   errorInfo?: ErrorInfo