Readme and doc updates

Also clears some minor warnings

Author: russhwolf

CHANGELOG.md

@@ -4,14 +4,14 @@
 
 - BREAKING: Rename Settings implementations to be based on the underlying API used rather than the platform
 
-| Old name | New name |
-| --- | --- |
-| AndroidSettings | SharedPreferencesSettings |
-| AppleSettings | NSUserDefaultsSettings |
-| JvmPreferencesSettings | PreferencesSettings |
-| JvmPropertiesSettings | PropertiesSettings |
-| WindowsSettings | RegistrySettings|
-| MockSettings | MapSettings |
+| Old name               | New name                  |
+|------------------------|---------------------------|
+| AndroidSettings        | SharedPreferencesSettings |
+| AppleSettings          | NSUserDefaultsSettings    |
+| JvmPreferencesSettings | PreferencesSettings       |
+| JvmPropertiesSettings  | PropertiesSettings        |
+| WindowsSettings        | RegistrySettings          |
+| MockSettings           | MapSettings               |
 
 - BREAKING: Migrate typed listeners from extension functions to members of ObservableSettings
 - BREAKING: Remove default values for defaultValue parameters

README.md

@@ -103,7 +103,7 @@ public fun ObservableSettings.getBooleanFlow(key: String, defaultValue: Boolean)
     createFlow(key, defaultValue, Settings::getBoolean, ObservableSettings::addBooleanListener)
 
 /**
- * Create a new flow, based on observing the given [key] as an nullable `Int`. This flow will immediately emit the
+ * Create a new flow, based on observing the given [key] as a nullable `Int`. This flow will immediately emit the
  * current value and then emit any subsequent values when the underlying `Settings` changes. When no value is present,
  * `null` will be emitted instead.
  */

multiplatform-settings-coroutines/src/commonMain/kotlin/com/russhwolf/settings/coroutines/CoroutineExtensions.kt

@@ -23,9 +23,8 @@ import com.russhwolf.settings.Settings
 import kotlinx.coroutines.flow.Flow
 import kotlin.test.Test
 import kotlin.test.assertEquals
-import kotlin.time.ExperimentalTime
 
-@OptIn(ExperimentalSettingsApi::class, ExperimentalTime::class)
+@OptIn(ExperimentalSettingsApi::class)
 abstract class BaseCoroutineExtensionsTest {
 
     abstract val settings: ObservableSettings

multiplatform-settings-coroutines/src/commonTest/kotlin/com/russhwolf/settings/coroutines/BaseCoroutineExtensionsTest.kt

@@ -14,8 +14,6 @@
  * limitations under the License.
  */
 
-@file:OptIn(ExperimentalCoroutinesApi::class)
-
 package com.russhwolf.settings.coroutines
 
 import com.russhwolf.settings.BaseSettingsTest
@@ -25,7 +23,6 @@ import com.russhwolf.settings.ObservableSettings
 import com.russhwolf.settings.Settings
 import kotlinx.coroutines.CoroutineScope
 import kotlinx.coroutines.Dispatchers
-import kotlinx.coroutines.ExperimentalCoroutinesApi
 
 // TODO we should have test-cases specific to SuspendSettings and FlowSettings, but until we do we test things by
 //  passing them through toBlockingSettings()

multiplatform-settings-coroutines/src/multithreadedTest/kotlin/com/russhwolf/settings/coroutines/ConvertersTest.kt

@@ -20,7 +20,6 @@ import kotlin.test.AfterTest
 import kotlin.test.Test
 import kotlin.test.assertEquals
 
-@OptIn(ExperimentalSettingsImplementation::class)
 abstract class NoArgTest {
     // clear() inside the lazy block in case subclasses need to do their setup first
     private val settings by lazy { Settings().also { it.clear() } }

multiplatform-settings-no-arg/src/commonTest/kotlin/com/russhwolf/settings/NoArgTest.kt

@@ -21,6 +21,6 @@ import java.util.prefs.Preferences
 /**
  * Returns a default [Settings] instance.
  *
- * On JVM, this uses the [JvmPreferencesSettings] implementation and delegates to [Preferences.userRoot]
+ * On JVM, this uses the [PreferencesSettings] implementation and delegates to [Preferences.userRoot]
  */
 public actual fun Settings(): Settings = PreferencesSettings(Preferences.userRoot())

multiplatform-settings-no-arg/src/jvmMain/kotlin/com/russhwolf/settings/NoArg.kt

@@ -22,11 +22,8 @@ package com.russhwolf.settings
  * This class allows storage of values with the [Int], [Long], [String], [Float], [Double], or [Boolean] types, using a
  * [String] reference as a key.
  *
- * The `MockSettings` implementation is intended for use in unit tests. The mock persisted state is represented by a
- * [Map] and can be injected at construction time.
- *
- * Operator extensions are defined in order to simplify usage. In addition, property delegates are provided for cleaner
- * syntax and better type-safety when interacting with values stored in a `Settings` instance.
+ * The `MapSettings` implementation is intended for use in unit tests. It differs from production implementations
+ * because the state exists only in-memory and has no mechanism for persistence.
  *
  * This class can be instantiated by wrapping a [MutableMap] or set of [Pair] entries, or via a [Factory].
  *
@@ -55,7 +52,7 @@ public class MapSettings public constructor(private val delegate: MutableMap<Str
     ) : Settings.Factory {
 
         /**
-         * Assigns the values in [delegate] to the cache that will be used to back any [MockSettings] this factory
+         * Assigns the values in [delegate] to the cache that will be used to back any [MapSettings] this factory
          * creates named [name]
          */
         public fun setCacheValues(name: String?, delegate: Map<String, Any>) {
@@ -65,7 +62,7 @@ public class MapSettings public constructor(private val delegate: MutableMap<Str
         }
 
         /**
-         * Assigns the values in [items] to the cache that will be used to back any [MockSettings] this factory
+         * Assigns the values in [items] to the cache that will be used to back any [MapSettings] this factory
          * creates named [name]
          */
         public fun setCacheValues(name: String?, vararg items: Pair<String, Any>) {
@@ -241,11 +238,12 @@ public class MapSettings public constructor(private val delegate: MutableMap<Str
     }
 
     /**
-     * A handle to a listener instance created in [addListener] so it can be passed to [removeListener]
+     * A handle to a listener instance returned by one of the addListener methods of [ObservableSettings], so it can be
+     * deactivated as needed.
      *
-     * In the [MockSettings] implementation this simply wraps a lambda parameter which is being called whenever a
+     * In the [MapSettings] implementation this simply wraps a lambda parameter which is being called whenever a
      * mutating API is called. Unlike platform implementations, this listener will NOT be called if the underlying map
-     * is mutated by something other than the `MockSettings` instance that originally created the listener.
+     * is mutated by something other than the `MapSettings` instance that originally created the listener.
      */
     public class Listener internal constructor(
         private val listeners: MutableList<() -> Any>,

multiplatform-settings-test/src/commonMain/kotlin/com/russhwolf/settings/MapSettings.kt

@@ -51,11 +51,7 @@ public class SharedPreferencesSettings @JvmOverloads public constructor(
     /**
      * A factory that can produce [Settings] instances.
      *
-     * This class can only be instantiated via a platform-specific constructor. It's purpose is so that `Settings`
-     * objects can be created in common code, so that the only platform-specific behavior necessary in order to use
-     * multiple `Settings` objects is the one-time creation of a single `Factory`.
-     *
-     * On the Android platform, this class creates `Settings` objects backed by [SharedPreferences]. It  can only be
+     * This class creates `Settings` objects backed by [SharedPreferences]. It can only be
      * created by supplying a [Context] instance. The `Factory` will hold onto a reference to the
      * [applicationContext][Context.getApplicationContext] property of the supplied `context` and will use that to
      * create [SharedPreferences] objects.
@@ -268,7 +264,8 @@ public class SharedPreferencesSettings @JvmOverloads public constructor(
     }
 
     /**
-     * A handle to a listener instance created in [addListener] so it can be passed to [removeListener]
+     * A handle to a listener instance returned by one of the addListener methods of [ObservableSettings], so it can be
+     * deactivated as needed.
      *
      * On the Android platform, this is a wrapper around [SharedPreferences.OnSharedPreferenceChangeListener].
      */

multiplatform-settings/src/androidMain/kotlin/com/russhwolf/settings/SharedPreferencesSettings.kt

@@ -81,7 +81,7 @@ class SharedPreferencesSettingsTest : BaseSettingsTest(factory) {
     @Test
     fun issue_108() {
         // In Android 11 (SDK level 30), we will get OnSharedPreferenceChangeListener callbacks with a null updatedKey
-        // if the user calls clear() on the SharedPreferenecs.Editor. On Multiplatform Settings versions 0.8.1 and
+        // if the user calls clear() on the SharedPreferences.Editor. On Multiplatform Settings versions 0.8.1 and
         // earlier, we assumed updatedKey was nonnull so this would crash.
 
         val preferences = context.getSharedPreferences("Settings", Context.MODE_PRIVATE)

multiplatform-settings/src/androidTest/kotlin/com/russhwolf/settings/SharedPreferencesSettingsTest.kt

@@ -101,10 +101,6 @@ public class KeychainSettings(vararg defaultProperties: Pair<CFStringRef?, CFTyp
     /**
      * A factory that can produce [Settings] instances.
      *
-     * This class can only be instantiated via a platform-specific constructor. It's purpose is so that `Settings`
-     * objects can be created in common code, so that the only platform-specific behavior necessary in order to use
-     * multiple `Settings` objects is the one-time creation of a single `Factory`.
-     *
      * This class creates `Settings` objects backed by the Apple keychain.
      */
     public class Factory : Settings.Factory {

multiplatform-settings/src/appleMain/kotlin/com/russhwolf/settings/KeychainSettings.kt

@@ -22,7 +22,6 @@ import platform.Foundation.NSNotificationCenter
 import platform.Foundation.NSUserDefaults
 import platform.Foundation.NSUserDefaultsDidChangeNotification
 import platform.darwin.NSObjectProtocol
-import kotlin.native.concurrent.AtomicReference
 
 /**
  * A collection of storage-backed key-value data
@@ -39,11 +38,6 @@ import kotlin.native.concurrent.AtomicReference
  *
  * On the iOS and macOS platforms, this class can be created by passing a [NSUserDefaults] instance which will be used as a
  * delegate, or via a [Factory].
- *
- * Note that this class is frozen on construction, and is safe to use in a multi-threaded environment. If the listener
- * APIs will be used in such an environment, then [useFrozenListeners] should be set to true on creation. In that case,
- * the block passed to [addListener] will be frozen as well so that it can safely be triggered from any thread. To avoid
- * freezing listeners, restrict interaction with this class to a single thread and set `useFrozenListeners` to `false`.
  */
 public class NSUserDefaultsSettings public constructor(
     private val delegate: NSUserDefaults
@@ -52,11 +46,7 @@ public class NSUserDefaultsSettings public constructor(
     /**
      * A factory that can produce [Settings] instances.
      *
-     * This class can only be instantiated via a platform-specific constructor. It's purpose is so that `Settings`
-     * objects can be created in common code, so that the only platform-specific behavior necessary in order to use
-     * multiple `Settings` objects is the one-time creation of a single `Factory`.
-     *
-     * On the iOS and macOS platforms, this class creates `Settings` objects backed by [NSUserDefaults].
+     * This class creates `Settings` objects backed by [NSUserDefaults].
      */
     public class Factory : Settings.Factory {
 
@@ -238,7 +228,8 @@ public class NSUserDefaultsSettings public constructor(
     }
 
     /**
-     * A handle to a listener instance created in [addListener] so it can be passed to [removeListener]
+     * A handle to a listener instance returned by one of the addListener methods of [ObservableSettings], so it can be
+     * deactivated as needed.
      *
      * On the iOS and macOS platforms, this is a wrapper around the object returned by [NSNotificationCenter.addObserverForName]
      */

multiplatform-settings/src/appleMain/kotlin/com/russhwolf/settings/NSUserDefaultsSettings.kt

@@ -89,7 +89,6 @@ class NSUserDefaultsSettingsBackgroundTest {
         assertEquals(false, incrementedOnMainThread.value)
     }
 
-    @OptIn(ExperimentalStdlibApi::class)
     @Test
     fun nonprimitive_value_across_threads(): Unit = memScoped {
         val mutableState = AtomicInt(0)

multiplatform-settings/src/appleTest/kotlin/com/russhwolf/settings/NSUserDefaultsSettingsBackgroundTest.kt

@@ -305,7 +305,7 @@ public interface ObservableSettings : Settings {
      * Adds a listener which will call the supplied [callback] anytime the value at [key] changes. A [SettingsListener]
      * reference is returned which can be used to halt callbacks by calling [deactivate()][SettingsListener.deactivate].
      * A strong reference should be held to the `SettingsListener` returned by this method in order to avoid it being
-     * garbaze-collected.
+     * garbage-collected.
      */
     @Suppress("DEPRECATION")
     public fun addDoubleOrNullListener(
@@ -328,11 +328,13 @@ public interface ObservableSettings : Settings {
 }
 
 /**
- * A handle to a listener instance returned by [ObservableSettings.addListener] so it can be deactivated as needed
+ * A handle to a listener instance returned by one of the addListener methods of [ObservableSettings], so it can be
+ * deactivated as needed.
  */
 public interface SettingsListener {
     /**
-     * Unsubscribes this [SettingsListener] from receiving updates to the value at the key it monitors
+     * Unsubscribes this [SettingsListener] from receiving updates to the value at the key it monitors. After calling
+     * this method you should no longer hold a reference to the listener.
      */
     public fun deactivate()
 }

multiplatform-settings/src/commonMain/kotlin/com/russhwolf/settings/Settings.kt

@@ -48,10 +48,6 @@ public class PreferencesSettings public constructor(
     /**
      * A factory that can produce [Settings] instances.
      *
-     * This class can only be instantiated via a platform-specific constructor. It's purpose is so that `Settings`
-     * objects can be created in common code, so that the only platform-specific behavior necessary in order to use
-     * multiple `Settings` objects is the one-time creation of a single `Factory`.
-     *
      * On the JVM platform, this class creates `Settings` objects backed by [Preferences].
      */
     public class Factory(private val rootPreferences: Preferences = Preferences.userRoot()) : Settings.Factory {
@@ -213,7 +209,8 @@ public class PreferencesSettings public constructor(
     }
 
     /**
-     * A handle to a listener instance created in [addListener] so it can be passed to [removeListener]
+     * A handle to a listener instance returned by one of the addListener methods of [ObservableSettings], so it can be
+     * deactivated as needed.
      *
      * On the JVM platform, this is a wrapper around [PreferenceChangeListener].
      */