doc: JavaDoc updates to WebBridge & Web authentication classes

Author: tal-mi

library/src/main/java/com/sap/cdc/android/sdk/feature/provider/web/WebAuthenticationProvider.kt

@@ -30,8 +30,22 @@ import kotlin.coroutines.resumeWithException
 import kotlin.coroutines.suspendCoroutine
 
 /**
- * Created by Tal Mirmelshtein on 10/06/2024
+ * Web-based social authentication provider.
+ * 
+ * Implements social login using WebView for providers that don't have native SDK support.
+ * Handles OAuth 1.0a flow with the CDC socialize.login endpoint.
+ * 
+ * @property socialProvider Social provider identifier (e.g., "twitter", "linkedin")
+ * @property siteConfig CDC site configuration
+ * @property session Optional existing session for authenticated requests
+ * 
+ * @author Tal Mirmelshtein
+ * @since 10/06/2024
+ * 
  * Copyright: SAP LTD.
+ * 
+ * @see IAuthenticationProvider
+ * @see WebLoginActivity
  */
 class WebAuthenticationProvider(
     private val socialProvider: String,
@@ -138,7 +152,10 @@ class WebAuthenticationProvider(
     }
 
     /**
-     * Generate authentication URI.
+     * Generates the OAuth authentication URI for social login.
+     * Includes GMID, nonce, and optional session signing for authenticated requests.
+     * @param hostActivity Host activity for package name in redirect URI
+     * @return Complete authentication URL
      */
     private fun generateUri(hostActivity: ComponentActivity): String {
         // Fetch gmid
@@ -180,7 +197,10 @@ class WebAuthenticationProvider(
     }
 
     /**
-     * Parse result session information.
+     * Parses session information from the authentication result.
+     * Extracts access token, secret, and expiration from intent extras.
+     * @param result Result intent containing session data
+     * @return Session object with credentials
      */
     private fun handleSessionInfo(result: Intent): Session {
         // Parse session information.
@@ -197,7 +217,10 @@ class WebAuthenticationProvider(
     }
 
     /**
-     * Parse error information. May result in a continuous flow to resolve the error.
+     * Parses error information from the authentication result.
+     * Extracts error code and message, optionally includes registration token.
+     * @param result Result intent containing error data
+     * @return CDCError with parsed error details
      */
     //TODO: Change flow to base response. Not handling CDCError as a object.
     private fun handleErrorInfo(result: Intent): CDCError {
@@ -227,4 +250,4 @@ class WebAuthenticationProvider(
         launcher?.unregister()
     }
 
-}
+}

library/src/main/java/com/sap/cdc/android/sdk/feature/provider/web/WebLoginActivity.kt

@@ -19,10 +19,19 @@ import com.sap.cdc.android.sdk.R
 import com.sap.cdc.android.sdk.extensions.parseQueryStringParams
 
 /**
- * Created by Tal Mirmelshtein on 10/06/2024
+ * WebView-based login activity for social authentication.
+ * 
+ * Displays a WebView for OAuth authentication with social providers that don't
+ * have native SDK support. Handles URL interception for OAuth callbacks and
+ * extracts authentication tokens from the redirect URI.
+ * 
+ * @author Tal Mirmelshtein
+ * @since 10/06/2024
+ * 
  * Copyright: SAP LTD.
+ * 
+ * @see WebAuthenticationProvider
  */
-
 class WebLoginActivity : ComponentActivity() {
 
     companion object {
@@ -64,10 +73,11 @@ class WebLoginActivity : ComponentActivity() {
         webView.loadUrl(uri!!)
     }
 
-    @SuppressLint("SetJavaScriptEnabled")
     /**
-     * Setting up main WebView widget.
+     * Configures the WebView with JavaScript enabled and custom WebViewClient.
+     * Handles page load progress and URL interception for OAuth callbacks.
      */
+    @SuppressLint("SetJavaScriptEnabled")
     private fun setupWebViewElement() {
         webView.settings.setSupportZoom(true)
         webView.settings.builtInZoomControls = true
@@ -103,7 +113,10 @@ class WebLoginActivity : ComponentActivity() {
     }
 
     /**
-     * Check login result on URL loading.
+     * Checks if the current URL is the OAuth redirect callback.
+     * Extracts authentication parameters from the URL fragment and returns them.
+     * @param uri The URI to check
+     * @return true if this is the callback URL, false otherwise
      */
     private fun loginResult(uri: Uri?): Boolean {
         if (uri == null) return false
@@ -137,11 +150,11 @@ class WebLoginActivity : ComponentActivity() {
     }
 
     /**
-     * Cancel flow on back press.
+     * Handles back button press by canceling the authentication flow.
      */
     override fun getOnBackInvokedDispatcher(): OnBackInvokedDispatcher {
         setResult(RESULT_CANCELED)
         return super.getOnBackInvokedDispatcher()
     }
 
-}
+}

library/src/main/java/com/sap/cdc/android/sdk/feature/screensets/ScreenSetsResult.kt

@@ -3,7 +3,18 @@ package com.sap.cdc.android.sdk.feature.screensets
 import com.sap.cdc.android.sdk.core.api.model.CDCError
 
 /**
- * Event data for ScreenSets events
+ * Event data container for ScreenSets lifecycle events.
+ * 
+ * Contains information about web-based authentication UI events triggered
+ * by user interactions or system state changes.
+ * 
+ * @property eventName The name of the event (e.g., "load", "login", "error")
+ * @property content Optional map containing event-specific data
+ * @property screenSetId Identifier of the screen set that triggered the event
+ * @property sourceContainerID Container ID where the event originated
+ * 
+ * @see ScreenSetsCallbacks
+ * @see WebBridgeJS
  */
 data class ScreenSetsEventData(
     val eventName: String,
@@ -13,7 +24,18 @@ data class ScreenSetsEventData(
 )
 
 /**
- * Error information for ScreenSets events
+ * Error information for ScreenSets operations.
+ * 
+ * Wraps error details from web-based authentication flows, providing
+ * context about what went wrong and where.
+ * 
+ * @property message Human-readable error message
+ * @property eventName Name of the event where the error occurred
+ * @property cdcError Structured CDC error object if available
+ * @property details Additional error context and metadata
+ * 
+ * @see CDCError
+ * @see ScreenSetsCallbacks.onError
  */
 data class ScreenSetsError(
     val message: String,
@@ -23,9 +45,24 @@ data class ScreenSetsError(
 )
 
 /**
- * Sealed class representing the result of ScreenSets operations
+ * Sealed class representing ScreenSets operation results.
+ * 
+ * Provides type-safe handling of either successful events or errors
+ * from web-based authentication flows.
+ * 
+ * @see ScreenSetsEventData
+ * @see ScreenSetsError
  */
 sealed class ScreenSetsResult {
+    /**
+     * Successful event result.
+     * @property eventData The event data
+     */
     data class Event(val eventData: ScreenSetsEventData) : ScreenSetsResult()
+    
+    /**
+     * Error result.
+     * @property screenSetsError The error information
+     */
     data class Error(val screenSetsError: ScreenSetsError) : ScreenSetsResult()
 }

library/src/main/java/com/sap/cdc/android/sdk/feature/screensets/WebBridgeJSEvent.kt

@@ -3,8 +3,20 @@ package com.sap.cdc.android.sdk.feature.screensets
 import com.sap.cdc.android.sdk.core.api.model.CDCError
 
 /**
- * Created by Tal Mirmelshtein on 13/06/2024
+ * Event wrapper for JavaScript bridge communication.
+ * 
+ * Encapsulates events from web-based ScreenSets, providing type-safe access
+ * to event data and factory methods for common events.
+ * 
+ * @property content Map containing event data including eventName and payload
+ * 
+ * @author Tal Mirmelshtein
+ * @since 13/06/2024
+ * 
  * Copyright: SAP LTD.
+ * 
+ * @see WebBridgeJS
+ * @see ScreenSetsEventData
  */
 class WebBridgeJSEvent(
     val content: Map<String, Any?>? = mapOf()
@@ -52,10 +64,17 @@ class WebBridgeJSEvent(
 }
 
 /**
- * Data class to hold JS evaluation request data.
+ * Container for JavaScript evaluation requests.
+ * 
+ * Holds data required to evaluate JavaScript in the WebView and
+ * optionally trigger follow-up events.
+ * 
+ * @property containerID The container ID where evaluation should occur
+ * @property evaluationString The JavaScript code to evaluate
+ * @property event Optional event to trigger after evaluation
  */
 data class WebBridgeJSEvaluation(
     val containerID: String,
     val evaluationString: String,
     val event: WebBridgeJSEvent?
-)
+)