/**
 * @summary: [AI: Provide a concise, one-sentence summary of the function's primary purpose.]
 *
 * @description: [AI: Elaborate on the summary. Explain the business logic, the problem this function solves, and its role in the application's feature or workflow.]
 *
 * @parameters:
 * - `paramName1` ({type}): [AI: Describe the parameter's purpose. Specify constraints (e.g., must not be null, must be a positive integer) and default values.]
 * - `paramName2` ({type}): [AI: Describe the parameter's purpose...]
 *
 * @returns:
 * - ({type}): [AI: Describe the value returned on successful execution. Explain the structure of the returned object if it's complex. If nothing is returned (void), state that.]
 *
 * @implementation-steps:
 * 1. [AI: Describe the first logical step of the implementation.]
 * 2. [AI: Describe the second step. Mention any specific algorithms used (e.g., binary search, recursion).]
 * 3. [AI: Continue for all significant steps.]
 *
 * @side-effects:
 * - [AI: List any state changes outside this function's scope (e.g., "Writes to the user's cache," "Makes a POST request to the /api/update endpoint," or "None").]
 *
 * @error-handling:
 * - Throws `{ErrorType}`: [AI: Explain when and why this specific error is thrown.]
 *
 * @complexity:
 * - Time: [AI: Estimate the time complexity (e.g., O(n), O(1), O(log n)) and briefly justify it based on the implementation steps.]
 * - Space: [AI: Estimate the space complexity and justify it.]
 * - Notes: [AI: Add any performance-related notes, like network latency, I/O bottlenecks, or if the function is CPU-intensive.]
 *
 * @assumptions:
 * - [AI: List any preconditions or system states that are assumed to be true before this function is called (e.g., "Assumes the user is already authenticated," or "Assumes the database connection is active"). If none, state "None".]
 *
 * @example:
 * ```dart
 * [AI: Provide a clear, runnable code example demonstrating how to use this function.]
 * ```
 */