Merge pull request #247 from Automattic/experimentation_readme_fix

Hide `ExPlat` as implementation detail. Update README.md for experimentation.

Author: wzieba

experimentation/README.md

@@ -2,62 +2,75 @@
 
 ## Introduction
 
-This module provides an SDK to communicate with Automattic-internal A/B testing service: ExPlat.
+This module provides an SDK for interfacing with the Automattic-internal A/B testing service, ExPlat.
 
-## Coordinates
+## Including the SDK
+
+To include the ExPlat SDK in your project, add the following dependency to your build configuration:
 
 ```groovy
 dependencies {
-    implementation 'com.automattic.tracks:experimentation:{recent_release}'
+    implementation 'com.automattic.tracks:experimentation:<recent_release_version_here>'
 }
 ```
 
 ## Usage
 
 ### Initialization
 
+To begin using the SDK, initialize the `VariationsRepository` with a set of experiments:
+
 ```kotlin
 val experiments = setOf(
     Experiment("experiment_1"),
     Experiment("experiment_2")
 )
 
-// If injected in a DI container, the repository should be a singleton
+// If using a DI container, ensure the repository is scoped as a singleton
 val repository: VariationsRepository = VariationsRepository.create(
     experiments = experiments
-    /* see KDoc documentation for detailed description of parameters */
+    // Refer to KDoc for a detailed description of the other parameters
 )
-// New variations will be available on the next application session. See KDoc for `VariationsRepository#getVariation`
-repository.configure(anonymousId = "currently_logged_in_user_id_or_random_uuid")
+
+// New variations will be reachable during the next application session.
+// For more information, check the KDoc for `VariationsRepository#getVariation`
+repository.initialize(anonymousId = "currently_logged_in_user_id_or_random_uuid")
 ```
 
 ### Getting variation
 
+Retrieve the specific variation for an experiment as follows:
+
 ```kotlin
 val variation = repository.getVariation("experiment_1")
 
 when (variation) {
     is Control -> {
-        // continue with control group
+        // Proceed with the control group behavior
     }
     is Treatment -> {
         println("Treatment group: ${variation.value}")
-        // apply treatment changes
+        // Implement the treatment variation
     }
 }
 ```
 
-### User logs out
+### Handling user logs out
+
+Upon user logout, clear the repository like this:
 
 ```kotlin
 repository.clear()
 ```
 
 ### Different user logs in
 
+When a different user logs in, re-initialize the repository with the new user's ID:
+
 ```kotlin
 repository.initialize(anonymousId = "new_user_id")
 ```
 
 ## Testing
-The SDK offers `VariantionsRepository` interface, which can be doubled in tests.
+
+The SDK provides a `VariationsRepository` interface for facilitating testing. This interface can be mocked or stubbed as required for unit or integration tests.

experimentation/api/experimentation.api

@@ -1,9 +1,3 @@
-public final class com/automattic/android/experimentation/ExPlat : com/automattic/android/experimentation/VariationsRepository {
-	public fun clear ()V
-	public fun getVariation-98D7FEw (Ljava/lang/String;)Lcom/automattic/android/experimentation/domain/Variation;
-	public fun initialize (Ljava/lang/String;Ljava/lang/String;)V
-}
-
 public final class com/automattic/android/experimentation/Experiment {
 	public static final synthetic fun box-impl (Ljava/lang/String;)Lcom/automattic/android/experimentation/Experiment;
 	public static fun constructor-impl (Ljava/lang/String;)Ljava/lang/String;
@@ -35,8 +29,8 @@ public abstract interface class com/automattic/android/experimentation/Variation
 }
 
 public final class com/automattic/android/experimentation/VariationsRepository$Companion {
-	public final fun create (Ljava/lang/String;Ljava/util/Set;Lcom/automattic/android/experimentation/ExperimentLogger;ZLjava/io/File;Lokhttp3/OkHttpClient;Lkotlinx/coroutines/CoroutineScope;Lkotlinx/coroutines/CoroutineDispatcher;)Lcom/automattic/android/experimentation/ExPlat;
-	public static synthetic fun create$default (Lcom/automattic/android/experimentation/VariationsRepository$Companion;Ljava/lang/String;Ljava/util/Set;Lcom/automattic/android/experimentation/ExperimentLogger;ZLjava/io/File;Lokhttp3/OkHttpClient;Lkotlinx/coroutines/CoroutineScope;Lkotlinx/coroutines/CoroutineDispatcher;ILjava/lang/Object;)Lcom/automattic/android/experimentation/ExPlat;
+	public final fun create (Ljava/lang/String;Ljava/util/Set;Lcom/automattic/android/experimentation/ExperimentLogger;ZLjava/io/File;Lokhttp3/OkHttpClient;Lkotlinx/coroutines/CoroutineScope;Lkotlinx/coroutines/CoroutineDispatcher;)Lcom/automattic/android/experimentation/VariationsRepository;
+	public static synthetic fun create$default (Lcom/automattic/android/experimentation/VariationsRepository$Companion;Ljava/lang/String;Ljava/util/Set;Lcom/automattic/android/experimentation/ExperimentLogger;ZLjava/io/File;Lokhttp3/OkHttpClient;Lkotlinx/coroutines/CoroutineScope;Lkotlinx/coroutines/CoroutineDispatcher;ILjava/lang/Object;)Lcom/automattic/android/experimentation/VariationsRepository;
 }
 
 public final class com/automattic/android/experimentation/VariationsRepository$DefaultImpls {

experimentation/src/main/java/com/automattic/android/experimentation/ExPlat.kt

@@ -8,7 +8,7 @@ import com.automattic.android.experimentation.repository.AssignmentsRepository
 import kotlinx.coroutines.CoroutineScope
 import kotlinx.coroutines.launch
 
-public class ExPlat internal constructor(
+internal class ExPlat internal constructor(
     private val platform: String,
     experiments: Set<Experiment>,
     private val logger: ExperimentLogger,

experimentation/src/main/java/com/automattic/android/experimentation/VariationsRepository.kt

@@ -67,7 +67,7 @@ public interface VariationsRepository {
             okhttpClient: OkHttpClient = OkHttpClient(),
             coroutineScope: CoroutineScope,
             dispatcher: CoroutineDispatcher = Dispatchers.IO,
-        ): ExPlat {
+        ): VariationsRepository {
             return ExPlat(
                 platform = platform,
                 experiments = experiments,

experimentation/src/test/java/com/automattic/android/experimentation/ExPlatTest.kt

@@ -120,7 +120,7 @@ internal class ExPlatTest {
     fun `initializing fetches assignments`() = runTest {
         enqueueSuccessfulNetworkResponse()
 
-        val exPlat = createExPlat()
+        createExPlat()
 
         assertThat(tempCache.latest).isEqualTo(testAssignment)
     }