docs(auth): add JSDoc comments to OAuth utilities

app/composables/useAuth.ts

@@ -42,6 +42,31 @@ export const useAuth = () => {
     return authMethods.oauth2.enabled ? authMethods.oauth2.providers : [];
   };
 
+  /**
+   * Initiates OAuth login flow with the specified provider.
+   *
+   * Handles various error scenarios with user-friendly messages:
+   * - **Unconfigured Provider**: "not configured" in error → Provider not set up in Pocketbase
+   * - **Denied Authorization**: "denied" or "cancel" in error → User cancelled OAuth popup
+   * - **Network Errors**: "network" or "fetch" in error → Connection issues
+   * - **Generic Errors**: All other errors → Fallback message for unexpected failures
+   *
+   * All errors are logged to console with `[useAuth]` prefix for debugging.
+   *
+   * @param provider - The OAuth provider name (e.g., 'google', 'microsoft')
+   * @throws Sets `error.value` with user-friendly message on failure
+   *
+   * @example
+   * ```typescript
+   * const { login, error } = useAuth()
+   *
+   * await login('google')
+   * if (error.value) {
+   *   // Display error.value.message to user
+   *   console.log(error.value.message) // "Login was cancelled. Please try again."
+   * }
+   * ```
+   */
   const login = async (provider: string) => {
     loading.value = true;
     error.value = null;
@@ -57,6 +82,7 @@ export const useAuth = () => {
       const err = pbError as Error;
       console.error('[useAuth] Login failed:', err);
 
+      // Error categorization for user-friendly messages
       const message = err?.message?.toLowerCase() || '';
       if (message.includes('not configured')) {
         error.value = new Error('This login provider is not available. Contact admin.');