From 4b33751127845e665548e025dc2cdf8baf69dcda Mon Sep 17 00:00:00 2001 From: Benoit Marty Date: Tue, 26 Apr 2022 13:39:56 +0200 Subject: [PATCH 1/7] Clarify + typo --- .github/ISSUE_TEMPLATE/release.yml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.github/ISSUE_TEMPLATE/release.yml b/.github/ISSUE_TEMPLATE/release.yml index c22b00e2e9..50a9cdf5fc 100644 --- a/.github/ISSUE_TEMPLATE/release.yml +++ b/.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: From 01be02abb57f346ac6e8ab0e926ecb82c9b8a8c3 Mon Sep 17 00:00:00 2001 From: Benoit Marty Date: Tue, 26 Apr 2022 13:41:17 +0200 Subject: [PATCH 2/7] Remove unused members --- .../internal/session/room/summary/RoomSummaryDataSource.kt | 4 ---- 1 file changed, 4 deletions(-) diff --git a/matrix-sdk-android/src/main/java/org/matrix/android/sdk/internal/session/room/summary/RoomSummaryDataSource.kt b/matrix-sdk-android/src/main/java/org/matrix/android/sdk/internal/session/room/summary/RoomSummaryDataSource.kt index 18a4f80547..96e8d3c73f 100644 --- a/matrix-sdk-android/src/main/java/org/matrix/android/sdk/internal/session/room/summary/RoomSummaryDataSource.kt +++ b/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? { From 9e2cae56439ec4164c15644ac504bb9b03baedc2 Mon Sep 17 00:00:00 2001 From: Benoit Marty Date: Wed, 27 Apr 2022 12:20:56 +0200 Subject: [PATCH 3/7] Clarify that default language is U.S. English --- CONTRIBUTING.md | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 053931cac5..52ccf47e6a 100644 --- a/CONTRIBUTING.md +++ b/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. From 250baf225c980aae2acbcc4f3315325fb8182335 Mon Sep 17 00:00:00 2001 From: Benoit Marty Date: Wed, 27 Apr 2022 16:31:53 +0200 Subject: [PATCH 4/7] Suppress legacy Riot classes from being documented. --- matrix-sdk-android/build.gradle | 10 ++++++---- 1 file changed, 6 insertions(+), 4 deletions(-) diff --git a/matrix-sdk-android/build.gradle b/matrix-sdk-android/build.gradle index a4a3dcee80..4165b60c56 100644 --- a/matrix-sdk-android/build.gradle +++ b/matrix-sdk-android/build.gradle @@ -19,13 +19,15 @@ 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) } - */ } } } From b319ef40bad028773f54594423cbd32909cf6808 Mon Sep 17 00:00:00 2001 From: Benoit Marty Date: Wed, 27 Apr 2022 16:52:45 +0200 Subject: [PATCH 5/7] Add files to document module and packages --- matrix-sdk-android/build.gradle | 3 +++ matrix-sdk-android/docs/modules.md | 3 +++ matrix-sdk-android/docs/packages.md | 3 +++ 3 files changed, 9 insertions(+) create mode 100644 matrix-sdk-android/docs/modules.md create mode 100644 matrix-sdk-android/docs/packages.md diff --git a/matrix-sdk-android/build.gradle b/matrix-sdk-android/build.gradle index 4165b60c56..2aab8510ce 100644 --- a/matrix-sdk-android/build.gradle +++ b/matrix-sdk-android/build.gradle @@ -28,6 +28,9 @@ dokkaHtml { 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") } } } diff --git a/matrix-sdk-android/docs/modules.md b/matrix-sdk-android/docs/modules.md new file mode 100644 index 0000000000..c6ae55b4e5 --- /dev/null +++ b/matrix-sdk-android/docs/modules.md @@ -0,0 +1,3 @@ +# Module matrix-sdk-android + +Doc for the module! diff --git a/matrix-sdk-android/docs/packages.md b/matrix-sdk-android/docs/packages.md new file mode 100644 index 0000000000..a229223f3f --- /dev/null +++ b/matrix-sdk-android/docs/packages.md @@ -0,0 +1,3 @@ +# Package org.matrix.android.sdk.api + +Doc for the package! From a27ecac59891d841d6f9d523565f21974d3e2716 Mon Sep 17 00:00:00 2001 From: Benoit Marty Date: Wed, 27 Apr 2022 17:23:32 +0200 Subject: [PATCH 6/7] Update the doc --- matrix-sdk-android/docs/modules.md | 17 ++++++++++++++++- matrix-sdk-android/docs/packages.md | 2 +- 2 files changed, 17 insertions(+), 2 deletions(-) diff --git a/matrix-sdk-android/docs/modules.md b/matrix-sdk-android/docs/modules.md index c6ae55b4e5..edf5af64d0 100644 --- a/matrix-sdk-android/docs/modules.md +++ b/matrix-sdk-android/docs/modules.md @@ -1,3 +1,18 @@ # Module matrix-sdk-android -Doc for the module! +## 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! diff --git a/matrix-sdk-android/docs/packages.md b/matrix-sdk-android/docs/packages.md index a229223f3f..ae7bee1b4e 100644 --- a/matrix-sdk-android/docs/packages.md +++ b/matrix-sdk-android/docs/packages.md @@ -1,3 +1,3 @@ # Package org.matrix.android.sdk.api -Doc for the package! +This is the root package of the API exposed by this SDK. From 246480eaed033047c580021a3c8e8a1822ade330 Mon Sep 17 00:00:00 2001 From: Benoit Marty Date: Thu, 28 Apr 2022 09:39:49 +0200 Subject: [PATCH 7/7] Changelog --- changelog.d/5854.doc | 1 + 1 file changed, 1 insertion(+) create mode 100644 changelog.d/5854.doc diff --git a/changelog.d/5854.doc b/changelog.d/5854.doc new file mode 100644 index 0000000000..38a1c756af --- /dev/null +++ b/changelog.d/5854.doc @@ -0,0 +1 @@ +Improve documentation of the project and of the SDK