diff --git a/libraries/matrix/api/src/main/kotlin/io/element/android/libraries/matrix/api/notification/NotificationService.kt b/libraries/matrix/api/src/main/kotlin/io/element/android/libraries/matrix/api/notification/NotificationService.kt
index 369587cd10..3a3fbeaa19 100644
--- a/libraries/matrix/api/src/main/kotlin/io/element/android/libraries/matrix/api/notification/NotificationService.kt
+++ b/libraries/matrix/api/src/main/kotlin/io/element/android/libraries/matrix/api/notification/NotificationService.kt
@@ -24,6 +24,9 @@ typealias GetNotificationDataResult = Result<Map<EventId, Result<NotificationDat
 interface NotificationService {
     /**
      * Fetch notifications for the specified event ids in the given rooms.
+     * Each event is resolved independently, so a partial answer is normal: see [GetNotificationDataResult] for how the two failure levels differ.
+     *
+     * @param ids the events to resolve, grouped by the room they belong to.
      */
     suspend fun getNotifications(ids: Map<RoomId, List<EventId>>): GetNotificationDataResult
 }
diff --git a/libraries/matrix/api/src/main/kotlin/io/element/android/libraries/matrix/api/notificationsettings/NotificationSettingsService.kt b/libraries/matrix/api/src/main/kotlin/io/element/android/libraries/matrix/api/notificationsettings/NotificationSettingsService.kt
index 7ae1ca4886..7226de9a9d 100644
--- a/libraries/matrix/api/src/main/kotlin/io/element/android/libraries/matrix/api/notificationsettings/NotificationSettingsService.kt
+++ b/libraries/matrix/api/src/main/kotlin/io/element/android/libraries/matrix/api/notificationsettings/NotificationSettingsService.kt
@@ -11,28 +11,114 @@ package io.element.android.libraries.matrix.api.notificationsettings
 import io.element.android.libraries.matrix.api.core.RoomId
 import io.element.android.libraries.matrix.api.room.RoomNotificationMode
 import io.element.android.libraries.matrix.api.room.RoomNotificationSettings
-import io.element.android.libraries.matrix.api.room.RoomNotificationSettingsState
 import kotlinx.coroutines.flow.SharedFlow
 
+/**
+ * Reads and writes the push rules of the account, which decide what generates a notification.
+ *
+ * Rules are account data shared across clients, so a change made here is visible on the user's other devices.
+ * Several methods take the encryption and one-to-one nature of a room, because Matrix keeps a separate default rule for each combination.
+ */
 interface NotificationSettingsService {
     /**
-     * State of the current room notification settings flow ([RoomNotificationSettingsState.Unknown] if not started).
+     * Emits every time the push rules change, whether from this client or another one, without saying what changed.
+     * Callers are expected to re-read the values they display; only the most recent signal is buffered.
      */
     val notificationSettingsChangeFlow: SharedFlow<Unit>
+
+    /**
+     * Returns the notification settings that apply to one room, which may come from a room specific rule or from the matching default.
+     *
+     * @param roomId the room to read the settings of.
+     * @param isEncrypted whether that room is encrypted, which selects the relevant default rule.
+     * @param isOneToOne whether that room is a direct message, which selects the relevant default rule.
+     */
     suspend fun getRoomNotificationSettings(roomId: RoomId, isEncrypted: Boolean, isOneToOne: Boolean): Result<RoomNotificationSettings>
+
+    /**
+     * Returns the default notification mode used by rooms that have no rule of their own.
+     *
+     * @param isEncrypted whether to read the default for encrypted rooms.
+     * @param isOneToOne whether to read the default for direct messages.
+     */
     suspend fun getDefaultRoomNotificationMode(isEncrypted: Boolean, isOneToOne: Boolean): Result<RoomNotificationMode>
+
+    /**
+     * Changes the default notification mode for a whole category of rooms.
+     *
+     * @param isEncrypted whether to change the default for encrypted rooms.
+     * @param mode the new default mode.
+     * @param isDM whether to change the default for direct messages.
+     */
     suspend fun setDefaultRoomNotificationMode(isEncrypted: Boolean, mode: RoomNotificationMode, isDM: Boolean): Result<Unit>
+
+    /**
+     * Sets a room specific notification mode, which from then on overrides the default for that room.
+     *
+     * @param roomId the room to change.
+     * @param mode the new mode for that room.
+     */
     suspend fun setRoomNotificationMode(roomId: RoomId, mode: RoomNotificationMode): Result<Unit>
+
+    /**
+     * Removes the room specific rule so the room follows the matching default again.
+     *
+     * @param roomId the room to reset.
+     */
     suspend fun restoreDefaultRoomNotificationMode(roomId: RoomId): Result<Unit>
+
+    /**
+     * Mutes a room, which is a room specific rule like any other and is undone by [unmuteRoom].
+     *
+     * @param roomId the room to mute.
+     */
     suspend fun muteRoom(roomId: RoomId): Result<Unit>
+
+    /**
+     * Unmutes a room, restoring either its previous room specific mode or the matching default.
+     *
+     * @param roomId the room to unmute.
+     * @param isEncrypted whether that room is encrypted, which selects the relevant default rule.
+     * @param isOneToOne whether that room is a direct message, which selects the relevant default rule.
+     */
     suspend fun unmuteRoom(roomId: RoomId, isEncrypted: Boolean, isOneToOne: Boolean): Result<Unit>
+
+    /** Whether being mentioned through `@room` generates a notification. */
     suspend fun isRoomMentionEnabled(): Result<Boolean>
+
+    /**
+     * Sets whether being mentioned through `@room` generates a notification.
+     *
+     * @param enabled true to be notified of `@room` mentions.
+     */
     suspend fun setRoomMentionEnabled(enabled: Boolean): Result<Unit>
+
+    /** Whether incoming calls generate a notification. */
     suspend fun isCallEnabled(): Result<Boolean>
+
+    /**
+     * Sets whether incoming calls generate a notification.
+     *
+     * @param enabled true to be notified of incoming calls.
+     */
     suspend fun setCallEnabled(enabled: Boolean): Result<Unit>
+
+    /** Whether room invitations generate a notification. */
     suspend fun isInviteForMeEnabled(): Result<Boolean>
+
+    /**
+     * Sets whether room invitations generate a notification.
+     *
+     * @param enabled true to be notified of invitations.
+     */
     suspend fun setInviteForMeEnabled(enabled: Boolean): Result<Unit>
+
+    /** The rooms that have an enabled rule of their own rather than following the defaults. */
     suspend fun getRoomsWithUserDefinedRules(): Result<List<RoomId>>
+
+    /** Whether the homeserver is able to push encrypted events to the device, which decides how much a notification can show before decryption. */
     suspend fun canHomeServerPushEncryptedEventsToDevice(): Result<Boolean>
+
+    /** The push rules as raw JSON, for debugging and bug reports; `null` when the server returned none. */
     suspend fun getRawPushRules(): Result<String?>
 }
diff --git a/libraries/matrix/api/src/main/kotlin/io/element/android/libraries/matrix/api/pusher/PushersService.kt b/libraries/matrix/api/src/main/kotlin/io/element/android/libraries/matrix/api/pusher/PushersService.kt
index 6764598235..1eafe8ab49 100644
--- a/libraries/matrix/api/src/main/kotlin/io/element/android/libraries/matrix/api/pusher/PushersService.kt
+++ b/libraries/matrix/api/src/main/kotlin/io/element/android/libraries/matrix/api/pusher/PushersService.kt
@@ -8,7 +8,21 @@
 
 package io.element.android.libraries.matrix.api.pusher
 
+/**
+ * Registers and removes the pusher of this session, i.e. the HTTP gateway the homeserver sends push notifications to.
+ */
 interface PushersService {
+    /**
+     * Registers or updates the pusher; calling it again with the same push key replaces the existing registration.
+     *
+     * @param setHttpPusherData the gateway URL, the push key and the other details the homeserver needs to reach the device.
+     */
     suspend fun setHttpPusher(setHttpPusherData: SetHttpPusherData): Result<Unit>
+
+    /**
+     * Removes the pusher, so the homeserver stops sending push notifications to this device.
+     *
+     * @param unsetHttpPusherData the push key and app id identifying the registration to remove.
+     */
     suspend fun unsetHttpPusher(unsetHttpPusherData: UnsetHttpPusherData): Result<Unit>
 }