Merge pull request #3324 from vector-im/feature/bma/doc_register

Add documentation on LoginWizard and RegistrationWizard (#3303)

CHANGES.md

@@ -23,7 +23,7 @@ Test:
  -
 
 Other changes:
- -
+ - Add documentation on LoginWizard and RegistrationWizard (#3303)
 
 Changes in Element 1.1.7 (2021-05-12)
 ===================================================

matrix-sdk-android/src/main/java/org/matrix/android/sdk/api/auth/AuthenticationService.kt

@@ -51,11 +51,15 @@ interface AuthenticationService {
 
     /**
      * Return a LoginWizard, to login to the homeserver. The login flow has to be retrieved first.
+     *
+     * See [LoginWizard] for more details
      */
     fun getLoginWizard(): LoginWizard
 
     /**
      * Return a RegistrationWizard, to create an matrix account on the homeserver. The login flow has to be retrieved first.
+     *
+     * See [RegistrationWizard] for more details.
      */
     fun getRegistrationWizard(): RegistrationWizard
 

matrix-sdk-android/src/main/java/org/matrix/android/sdk/api/auth/login/LoginWizard.kt

@@ -17,34 +17,46 @@
 package org.matrix.android.sdk.api.auth.login
 
 import org.matrix.android.sdk.api.session.Session
-import org.matrix.android.sdk.api.util.Cancelable
 
+/**
+ * Set of methods to be able to login to an existing account on a homeserver.
+ *
+ * More documentation can be found in the file https://github.com/vector-im/element-android/blob/main/docs/signin.md
+ */
 interface LoginWizard {
-
     /**
-     * @param login the login field
+     * Login to the homeserver.
-     * @param password the password field
+     *
+     * @param login the login field. Can be a user name, or a msisdn (email or phone number) associated to the account
+     * @param password the password of the account
      * @param deviceName the initial device name
-     * @param callback  the matrix callback on which you'll receive the result of authentication.
+     * @return a [Session] if the login is successful
-     * @return a [Cancelable]
      */
     suspend fun login(login: String,
                       password: String,
                       deviceName: String): Session
 
     /**
-     * Exchange a login token to an access token
+     * Exchange a login token to an access token.
+     *
+     * @param loginToken login token, obtain when login has happen in a WebView, using SSO
+     * @return a [Session] if the login is successful
      */
     suspend fun loginWithToken(loginToken: String): Session
 
     /**
-     * Reset user password
+     * Ask the homeserver to reset the user password. The password will not be reset until
+     * [resetPasswordMailConfirmed] is successfully called.
+     *
+     * @param email an email previously associated to the account the user wants the password to be reset.
+     * @param newPassword the desired new password
      */
     suspend fun resetPassword(email: String,
                               newPassword: String)
 
     /**
      * Confirm the new password, once the user has checked their email
+     * When this method succeed, tha account password will be effectively modified.
      */
     suspend fun resetPasswordMailConfirmed()
 }

matrix-sdk-android/src/main/java/org/matrix/android/sdk/api/auth/registration/RegistrationWizard.kt

@@ -16,32 +16,98 @@
 
 package org.matrix.android.sdk.api.auth.registration
 
+/**
+ * Set of methods to be able to create an account on a homeserver.
+ *
+ * Common scenario to register an account successfully:
+ *  - Call [getRegistrationFlow] to check that you application supports all the mandatory registration stages
+ *  - Call [createAccount] to start the account creation
+ *  - Fulfill all mandatory stages using the methods [performReCaptcha] [acceptTerms] [dummy], etc.
+ *
+ * More documentation can be found in the file https://github.com/vector-im/element-android/blob/main/docs/signup.md
+ * and https://matrix.org/docs/spec/client_server/latest#account-registration-and-management
+ */
 interface RegistrationWizard {
-
+    /**
+     * Call this method to get the possible registration flow of the current homeserver.
+     * It can be useful to ensure that your application implementation supports all the stages
+     * required to create an account. If it is not the case, you will have to use the web fallback
+     * to let the user create an account with your application.
+     * See [org.matrix.android.sdk.api.auth.AuthenticationService.getFallbackUrl]
+     */
     suspend fun getRegistrationFlow(): RegistrationResult
 
+    /**
+     * Can be call to check is the desired userName is available for registration on the current homeserver.
+     * It may also fails if the desired userName is not correctly formatted or does not follow any restriction on
+     * the homeserver. Ex: userName with only digits may be rejected.
+     * @param userName the desired username. Ex: "alice"
+     */
+    suspend fun registrationAvailable(userName: String): RegistrationAvailability
+
+    /**
+     * This is the first method to call in order to create an account and start the registration process.
+     *
+     * @param userName the desired username. Ex: "alice"
+     * @param password the desired password
+     * @param initialDeviceDisplayName the device display name
+     */
     suspend fun createAccount(userName: String?,
                               password: String?,
                               initialDeviceDisplayName: String?): RegistrationResult
 
+    /**
+     * Perform the "m.login.recaptcha" stage.
+     *
+     * @param response the response from ReCaptcha
+     */
     suspend fun performReCaptcha(response: String): RegistrationResult
 
+    /**
+     * Perform the "m.login.terms" stage.
+     */
     suspend fun acceptTerms(): RegistrationResult
 
+    /**
+     * Perform the "m.login.dummy" stage.
+     */
     suspend fun dummy(): RegistrationResult
 
+    /**
+     * Perform the "m.login.email.identity" or "m.login.msisdn" stage.
+     *
+     * @param threePid the threePid to add to the account. If this is an email, the homeserver will send an email
+     * to validate it. For a msisdn a SMS will be sent.
+     */
     suspend fun addThreePid(threePid: RegisterThreePid): RegistrationResult
 
+    /**
+     * Ask the homeserver to send again the current threePid (email or msisdn).
+     */
     suspend fun sendAgainThreePid(): RegistrationResult
 
+    /**
+     * Send the code received by SMS to validate a msisdn.
+     * If the code is correct, the registration request will be executed to validate the msisdn.
+     */
     suspend fun handleValidateThreePid(code: String): RegistrationResult
 
+    /**
+     * Useful to poll the homeserver when waiting for the email to be validated by the user.
+     * Once the email is validated, this method will return successfully.
+     * @param delayMillis the SDK can wait before sending the request
+     */
     suspend fun checkIfEmailHasBeenValidated(delayMillis: Long): RegistrationResult
 
-    suspend fun registrationAvailable(userName: String): RegistrationAvailability
+    /**
-
+     * This is the current ThreePid, waiting for validation. The SDK will store it in database, so it can be
+     * restored even if the app has been killed during the registration
+     */
     val currentThreePid: String?
 
-    // True when login and password has been sent with success to the homeserver
+    /**
+     * True when login and password have been sent with success to the homeserver, i.e. [createAccount] has been
+     * called successfully.
+     */
     val isRegistrationStarted: Boolean
 }

matrix-sdk-android/src/main/java/org/matrix/android/sdk/api/session/room/Room.kt

@@ -83,7 +83,7 @@ interface Room :
      * @param beforeLimit how many events before the result are returned.
      * @param afterLimit how many events after the result are returned.
      * @param includeProfile requests that the server returns the historic profile information for the users that sent the events that were returned.
-     * @param callback Callback to get the search result
+     * @return The search result
      */
     suspend fun search(searchTerm: String,
                nextBatch: String?,

vector/src/main/java/im/vector/app/core/utils/ExternalApplicationsUtil.kt

@@ -509,7 +509,7 @@ fun selectTxtFileToWrite(
  * @param sourceFile     the file source path
  * @param dstDirPath     the dst path
  * @param outputFilename optional the output filename
- * @param callback       the asynchronous callback
+ * @return               the created file
  */
 @Suppress("DEPRECATION")
 fun saveFileIntoLegacy(sourceFile: File, dstDirPath: File, outputFilename: String?): File? {