From 289f27b73814573d548b54d3209a620913711a4a Mon Sep 17 00:00:00 2001
From: Benoit Marty <benoit@matrix.org>
Date: Tue, 24 May 2022 16:03:09 +0200
Subject: [PATCH] Add some Kdoc

---
 .../api/RoomDisplayNameFallbackProvider.kt    |  8 +++++
 .../sdk/api/query/ActiveSpaceFilter.kt        |  4 +++
 .../session/room/RoomSummaryQueryParams.kt    | 35 +++++++++++++++++--
 3 files changed, 45 insertions(+), 2 deletions(-)

diff --git a/matrix-sdk-android/src/main/java/org/matrix/android/sdk/api/RoomDisplayNameFallbackProvider.kt b/matrix-sdk-android/src/main/java/org/matrix/android/sdk/api/RoomDisplayNameFallbackProvider.kt
index a34dbcc196..3c376b55ee 100644
--- a/matrix-sdk-android/src/main/java/org/matrix/android/sdk/api/RoomDisplayNameFallbackProvider.kt
+++ b/matrix-sdk-android/src/main/java/org/matrix/android/sdk/api/RoomDisplayNameFallbackProvider.kt
@@ -16,6 +16,14 @@
 
 package org.matrix.android.sdk.api
 
+/**
+ * This interface exists to let the implementation provide localized room display name fallback.
+ * The methods can be called when the room has no name, i.e. its `m.room.name` state event does not exist or
+ * the name in it is an empty String.
+ * It allows the SDK to store the room name fallback into the local storage and so let the client do
+ * queries on the room name.
+ * *Limitation*: if the locale of the device changes, the methods will not be called again.
+ */
 interface RoomDisplayNameFallbackProvider {
     fun getNameForRoomInvite(): String
     fun getNameForEmptyRoom(isDirect: Boolean, leftMemberNames: List<String>): String
diff --git a/matrix-sdk-android/src/main/java/org/matrix/android/sdk/api/query/ActiveSpaceFilter.kt b/matrix-sdk-android/src/main/java/org/matrix/android/sdk/api/query/ActiveSpaceFilter.kt
index 48619b9394..145c7f8bf4 100644
--- a/matrix-sdk-android/src/main/java/org/matrix/android/sdk/api/query/ActiveSpaceFilter.kt
+++ b/matrix-sdk-android/src/main/java/org/matrix/android/sdk/api/query/ActiveSpaceFilter.kt
@@ -16,6 +16,10 @@
 
 package org.matrix.android.sdk.api.query
 
+/**
+ * Filter to be used to do room queries.
+ * @see [org.matrix.android.sdk.api.session.room.RoomSummaryQueryParams]
+ */
 sealed class ActiveSpaceFilter {
     object None : ActiveSpaceFilter()
     data class ActiveSpace(val currentSpaceId: String?) : ActiveSpaceFilter()
diff --git a/matrix-sdk-android/src/main/java/org/matrix/android/sdk/api/session/room/RoomSummaryQueryParams.kt b/matrix-sdk-android/src/main/java/org/matrix/android/sdk/api/session/room/RoomSummaryQueryParams.kt
index 92d3cff315..743ea65664 100644
--- a/matrix-sdk-android/src/main/java/org/matrix/android/sdk/api/session/room/RoomSummaryQueryParams.kt
+++ b/matrix-sdk-android/src/main/java/org/matrix/android/sdk/api/session/room/RoomSummaryQueryParams.kt
@@ -47,18 +47,49 @@ fun spaceSummaryQueryParams(init: (RoomSummaryQueryParams.Builder.() -> Unit) =
 }
 
 /**
- * This class can be used to filter room summaries to use with:
- * [org.matrix.android.sdk.api.session.room.Room] and [org.matrix.android.sdk.api.session.room.RoomService].
+ * This class can be used to filter room summaries to use with [RoomService].
+ * It provides a [Builder].
+ * [roomSummaryQueryParams] and [spaceSummaryQueryParams] can also be used to build an instance of this class.
  */
 data class RoomSummaryQueryParams(
+        /**
+         * Query for the displayName of the room. The display name can be the value of the state event,
+         * or a value returned by [org.matrix.android.sdk.api.RoomDisplayNameFallbackProvider].
+         */
         val displayName: QueryStringValue,
+        /**
+         * Query for the canonical alias of the room.
+         */
         val canonicalAlias: QueryStringValue,
+        /**
+         * Used to filter room by membership.
+         */
         val memberships: List<Membership>,
+        /**
+         * Used to filter room by room category.
+         */
         val roomCategoryFilter: RoomCategoryFilter?,
+        /**
+         * Used to filter room by room tag.
+         */
         val roomTagQueryFilter: RoomTagQueryFilter?,
+        /**
+         * Used to filter room by room type.
+         * @see [includeType]
+         */
         val excludeType: List<String?>?,
+        /**
+         * Used to filter room by room type.
+         * @see [excludeType]
+         */
         val includeType: List<String?>?,
+        /**
+         * Used to filter room using the current space.
+         */
         val activeSpaceFilter: ActiveSpaceFilter?,
+        /**
+         * Used to filter room using the current group.
+         */
         val activeGroupId: String? = null
 ) {