Add KDoc to the libraries/pushproviders API interfaces

Document PusherSubscriber and PushHandler at the interface level, document the
PushProvider members that had none, and add the missing @param entries.

Notable points: getCurrentDistributor also returns null when the stored
distributor is no longer installed, rotateToken throws unless canRotateToken is
true, and handleInvalid records the payload in the push history for diagnosis.

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

libraries/pushproviders/api/src/main/kotlin/io/element/android/libraries/pushproviders/api/PushHandler.kt

@@ -8,6 +8,9 @@
 
 package io.element.android.libraries.pushproviders.api
 
+/**
+ * Entry point for the pushes coming from any provider, which resolves them into notifications.
+ */
 interface PushHandler {
     /**
      * Handle a push received from the provider.
@@ -22,7 +25,10 @@ interface PushHandler {
     ): Boolean
 
     /**
-     * Handle an invalid push received from the provider.
+     * Handle an invalid push received from the provider, which is recorded in the push history so it can be diagnosed.
+     *
+     * @param providerInfo an identifier of the provider that sent the push, for logging and debugging purposes.
+     * @param data the raw payload that could not be understood.
      */
     suspend fun handleInvalid(
         providerInfo: String,

libraries/pushproviders/api/src/main/kotlin/io/element/android/libraries/pushproviders/api/PushProvider.kt

@@ -37,33 +37,54 @@ interface PushProvider {
 
     /**
      * Register the pusher to the homeserver.
+     *
+     * @param matrixClient the session to register the pusher for.
+     * @param distributor the distributor to route the notifications through.
      */
     suspend fun registerWith(matrixClient: MatrixClient, distributor: Distributor): Result<Unit>
 
     /**
-     * Return the current distributor, or null if none.
+     * Return the current distributor as its raw stored value, or null if none.
+     *
+     * @param sessionId the session to read the distributor of.
      */
     suspend fun getCurrentDistributorValue(sessionId: SessionId): String?
 
     /**
-     * Return the current distributor, or null if none.
+     * Return the current distributor, or null if none, which also happens when the stored one is no longer installed.
+     *
+     * @param sessionId the session to read the distributor of.
      */
     suspend fun getCurrentDistributor(sessionId: SessionId): Distributor?
 
     /**
      * Unregister the pusher.
+     *
+     * @param matrixClient the session to unregister the pusher of.
      */
     suspend fun unregister(matrixClient: MatrixClient): Result<Unit>
 
     /**
      * To invoke when the session is deleted.
+     *
+     * @param sessionId the session that has been removed, whose provider-side data should be cleaned up.
      */
     suspend fun onSessionDeleted(sessionId: SessionId)
 
+    /**
+     * The gateway and push key currently in use, for display in the troubleshooting screens; `null` when not registered.
+     *
+     * @param sessionId the session to read the configuration of.
+     */
     suspend fun getPushConfig(sessionId: SessionId): Config?
 
+    /** Whether this provider can renew its push token on demand, which not every provider supports. */
     fun canRotateToken(): Boolean
 
+    /**
+     * Renews the push token, which is one of the recovery steps offered when notifications stop arriving.
+     * Throws when [canRotateToken] is `false`.
+     */
     suspend fun rotateToken(): Result<Unit> {
         error("rotateToken() not implemented, you need to override this method in your implementation")
     }

libraries/pushproviders/api/src/main/kotlin/io/element/android/libraries/pushproviders/api/PusherSubscriber.kt

@@ -11,14 +11,25 @@ package io.element.android.libraries.pushproviders.api
 import io.element.android.libraries.matrix.api.MatrixClient
 import io.element.android.libraries.matrix.api.exception.ClientException
 
+/**
+ * Registers and removes a pusher on the homeserver on behalf of a push provider, so every provider agrees on the parameters sent.
+ */
 interface PusherSubscriber {
     /**
      * Register a pusher. Note that failure will be a [RegistrationFailure].
+     *
+     * @param matrixClient the session to register the pusher for.
+     * @param pushKey the token identifying this device with the gateway.
+     * @param gateway the URL the homeserver should send the notifications to.
      */
     suspend fun registerPusher(matrixClient: MatrixClient, pushKey: String, gateway: String): Result<Unit>
 
     /**
      * Unregister a pusher.
+     *
+     * @param matrixClient the session to unregister the pusher of.
+     * @param pushKey the token of the registration to remove.
+     * @param gateway the gateway of the registration to remove.
      */
     suspend fun unregisterPusher(matrixClient: MatrixClient, pushKey: String, gateway: String): Result<Unit>
 }