diff --git a/libraries/oauth/api/src/main/kotlin/io/element/android/libraries/oauth/api/OAuthActionFlow.kt b/libraries/oauth/api/src/main/kotlin/io/element/android/libraries/oauth/api/OAuthActionFlow.kt
index c6791e3197..7cb35de176 100644
--- a/libraries/oauth/api/src/main/kotlin/io/element/android/libraries/oauth/api/OAuthActionFlow.kt
+++ b/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()
 }
diff --git a/libraries/oauth/api/src/main/kotlin/io/element/android/libraries/oauth/api/OAuthIntentResolver.kt b/libraries/oauth/api/src/main/kotlin/io/element/android/libraries/oauth/api/OAuthIntentResolver.kt
index 2091a86db4..5187649298 100644
--- a/libraries/oauth/api/src/main/kotlin/io/element/android/libraries/oauth/api/OAuthIntentResolver.kt
+++ b/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?
 }