Merge pull request #5854 from vector-im/feature/bma/small_fixies

Documentation update

.github/ISSUE_TEMPLATE/release.yml

@@ -106,7 +106,7 @@ body:
 
         https://github.com/matrix-org/matrix-android-sdk2-sample
 
-        - [ ] Update the dependency to the new version of the SDK2. It can take some time for MavenCentral to make the librarie available. You can check status on https://repo1.maven.org/maven2/org/matrix/android/matrix-android-sdk2/
+        - [ ] Update the dependency to the new version of the SDK2. It can take a few minutes for MavenCentral to make the library available. You can check status on https://repo1.maven.org/maven2/org/matrix/android/matrix-android-sdk2/
         - [ ] Build and run the sample, you may have to fix some API break
         - [ ] Commit and push directly on `main`
     validations:

CONTRIBUTING.md

@@ -124,7 +124,9 @@ As a general rule, please never edit or add or remove translations to the projec
 
 #### Adding new string
 
-When adding new string resources, please only add new entries in file `value/strings.xml`. Translations will be added later by the community of translators using Weblate.
+When adding new string resources, please only add new entries in the file `value/strings.xml`. Translations will be added later by the community of translators using Weblate.
+
+The file `value/strings.xml` must only contain American English (U. S. English) values, as this is the default language of the Android operating system. So for instance, please use "color" instead of "colour". Element Android will still use the language set on the system by the user, like any other Android applications which provide translations. The system language can be any other English language variants, or any other languages. Note that this is also possible to override the system language using the Element Android in-app language settings.
 
 New strings can be added anywhere in the file `value/strings.xml`, not necessarily at the end of the file. Generally, it's even better to add the new strings in some dedicated section per feature, and not at the end of the file, to avoid merge conflict between 2 PR adding strings at the end of the same file.
 

changelog.d/5854.doc

@@ -0,0 +1 @@
+Improve documentation of the project and of the SDK

matrix-sdk-android/build.gradle

@@ -19,13 +19,18 @@ dokkaHtml {
         configureEach {
             // Emit warnings about not documented members.
             reportUndocumented.set(true)
-            // Suppress package legacy riot. Sadly this does not work
-            /*
+            // Suppress legacy Riot's packages.
             perPackageOption {
-                prefix.set("org.matrix.android.sdk.internal.legacy.riot")
+                matchingRegex.set("org.matrix.android.sdk.internal.legacy.riot")
                 suppress.set(true)
             }
-             */
+            perPackageOption {
+                matchingRegex.set("org.matrix.androidsdk.crypto.data")
+                suppress.set(true)
+            }
+            // List of files with module and package documentation
+            // https://kotlinlang.org/docs/reference/kotlin-doc.html#module-and-package-documentation
+            includes.from("./docs/modules.md", "./docs/packages.md")
         }
     }
 }

matrix-sdk-android/docs/modules.md

@@ -0,0 +1,18 @@
+# Module matrix-sdk-android
+
+## Welcome to the matrix-sdk-android documentation!
+
+This pages list the complete API that this SDK is exposing to a client application.
+
+*We are still building the documentation, so everything is not documented yet.*
+
+A few entry points:
+
+- **Matrix**: The app will have to create and manage a Matrix object.
+- From this **Matrix** object, you will be able to get various services, including the **AuthenticationService**.
+- With this **AuthenticationService** you will be able to get an existing **Session**, or create one using a **LoginWizard** or a **RegistrationWizard**, which will finally give you a **Session**.
+- From the **Session**, you will be able to retrieve many Services, including the **RoomService**.
+- From the **RoomService**, you will be able to list the rooms, create a **Room**, and get a specific **Room**.
+- And from a **Room**, you will be able to do many things, including get a **Timeline**, send messages, etc.
+
+Please read the whole documentation to learn more!

matrix-sdk-android/docs/packages.md

@@ -0,0 +1,3 @@
+# Package org.matrix.android.sdk.api
+
+This is the root package of the API exposed by this SDK.

matrix-sdk-android/src/main/java/org/matrix/android/sdk/internal/session/room/summary/RoomSummaryDataSource.kt

@@ -26,7 +26,6 @@ import com.zhuinden.monarchy.Monarchy
 import io.realm.Realm
 import io.realm.RealmQuery
 import io.realm.kotlin.where
-import org.matrix.android.sdk.api.MatrixCoroutineDispatchers
 import org.matrix.android.sdk.api.query.ActiveSpaceFilter
 import org.matrix.android.sdk.api.query.RoomCategoryFilter
 import org.matrix.android.sdk.api.query.isNormalized
@@ -43,7 +42,6 @@ import org.matrix.android.sdk.api.session.room.summary.RoomAggregateNotification
 import org.matrix.android.sdk.api.session.space.SpaceSummaryQueryParams
 import org.matrix.android.sdk.api.util.Optional
 import org.matrix.android.sdk.api.util.toOptional
-import org.matrix.android.sdk.internal.database.RealmSessionProvider
 import org.matrix.android.sdk.internal.database.mapper.RoomSummaryMapper
 import org.matrix.android.sdk.internal.database.model.RoomSummaryEntity
 import org.matrix.android.sdk.internal.database.model.RoomSummaryEntityFields
@@ -57,10 +55,8 @@ import javax.inject.Inject
 
 internal class RoomSummaryDataSource @Inject constructor(
         @SessionDatabase private val monarchy: Monarchy,
-        private val realmSessionProvider: RealmSessionProvider,
         private val roomSummaryMapper: RoomSummaryMapper,
         private val queryStringValueProcessor: QueryStringValueProcessor,
-        private val coroutineDispatchers: MatrixCoroutineDispatchers
 ) {
 
     fun getRoomSummary(roomIdOrAlias: String): RoomSummary? {