Add KDoc to the libraries/oauth API interfaces

Document OAuthIntentResolver and OAuthActionFlow along with their members.

OAuthActionFlow now explains why it exists rather than the result simply being
returned: the activity that receives the redirect and the login screen waiting for
it are not in the same navigation subtree.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

libraries/oauth/api/src/main/kotlin/io/element/android/libraries/oauth/api/OAuthActionFlow.kt

@@ -10,8 +10,26 @@ package io.element.android.libraries.oauth.api
 
 import kotlinx.coroutines.flow.FlowCollector
 
+/**
+ * Carries the OAuth redirect from the activity that receives it to the login screen waiting for it.
+ *
+ * The two are not in the same navigation subtree, so the result cannot simply be returned.
+ */
 interface OAuthActionFlow {
+    /**
+     * Publishes the action just received, to be picked up by whoever is collecting.
+     *
+     * @param oAuthAction the action resolved from the redirect intent.
+     */
     fun post(oAuthAction: OAuthAction)
+
+    /**
+     * Observes the published actions; `null` is emitted when there is nothing pending.
+     *
+     * @param collector the collector to feed.
+     */
     suspend fun collect(collector: FlowCollector<OAuthAction?>)
+
+    /** Clears the pending action, so it is not handled twice. */
     fun reset()
 }

libraries/oauth/api/src/main/kotlin/io/element/android/libraries/oauth/api/OAuthIntentResolver.kt

@@ -10,6 +10,13 @@ package io.element.android.libraries.oauth.api
 
 import android.content.Intent
 
+/**
+ * Recognises the redirect the authentication server sends the user back with once they have signed in or cancelled.
+ */
 interface OAuthIntentResolver {
+    /**
+     * @param intent the intent the app was resumed with.
+     * @return the action to carry out, or `null` when the intent is not an OAuth redirect.
+     */
     fun resolve(intent: Intent): OAuthAction?
 }