creating separate creator for the matrix instance to avoid ambiguous non singleton/duplicated singleton usages

- also documents the static methods

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

@@ -99,12 +99,28 @@ class Matrix private constructor(context: Context, matrixConfiguration: MatrixCo
         private lateinit var instance: Matrix
         private val isInit = AtomicBoolean(false)
 
+        /**
+         * Creates a new instance of Matrix, it's recommend to manage this instance as a singleton.
+         * To make use of the built in singleton use Matrix.initialise() and/or Matrix.getInstance(context) instead
+         **/
+        fun createInstance(context: Context, matrixConfiguration: MatrixConfiguration): Matrix {
+            return Matrix(context.applicationContext, matrixConfiguration)
+        }
+
+        /**
+         * Initializes a singleton instance of Matrix for the given MatrixConfiguration
+         * This instance will be returned by Matrix.getInstance(context)
+         */
         fun initialize(context: Context, matrixConfiguration: MatrixConfiguration) {
             if (isInit.compareAndSet(false, true)) {
                 instance = Matrix(context.applicationContext, matrixConfiguration)
             }
         }
 
+        /**
+         * Either provides an already initialized singleton Matrix instance or queries the application context for a MatrixConfiguration.Provider
+         * to lazily create and store the instance.
+         */
         fun getInstance(context: Context): Matrix {
             if (isInit.compareAndSet(false, true)) {
                 val appContext = context.applicationContext

vector/src/androidTest/java/im/vector/app/core/utils/TestMatrixHelper.kt

@@ -26,6 +26,5 @@ fun getMatrixInstance(): Matrix {
     val configuration = MatrixConfiguration(
             roomDisplayNameFallbackProvider = VectorRoomDisplayNameFallbackProvider(context)
     )
-    Matrix.initialize(context, configuration)
+    return Matrix.createInstance(context, configuration)
-    return Matrix.getInstance(context)
 }

vector/src/main/java/im/vector/app/core/di/SingletonModule.kt

@@ -120,8 +120,7 @@ object VectorStaticModule {
     @Provides
     @Singleton
     fun providesMatrix(context: Context, configuration: MatrixConfiguration): Matrix {
-        Matrix.initialize(context, configuration)
+        return Matrix.createInstance(context, configuration)
-        return Matrix.getInstance(context)
     }
 
     @Provides