Add some provider documentation

commons-provider/src/main/kotlin/xyz/xenondevs/commons/provider/BasicProviders.kt

@@ -11,6 +11,7 @@ val NULL_PROVIDER: Provider<Nothing?> = provider(null)
 
 /**
  * Creates a new [Provider] that loads its value using the given [lazyValue] function.
+ * [lazyValue] should be a pure function.
  */
 fun <T> provider(lazyValue: () -> T): Provider<T> =
     object : AbstractProvider<T>(ReentrantLock()) {
@@ -47,6 +48,7 @@ fun <T> mutableProvider(initialValue: T): MutableProvider<T> =
 
 /**
  * Creates a new [MutableProvider] that loads its value using the given [lazyValue] function.
+ * [lazyValue] should be a pure function.
  */
 fun <T> mutableProvider(lazyValue: () -> T): MutableProvider<T> =
     object : AbstractProvider<T>(ReentrantLock()) {
@@ -60,6 +62,7 @@ fun <T> mutableProvider(lazyValue: () -> T): MutableProvider<T> =
 /**
  * Creates a new [MutableProvider] that loads its value using the given [lazyValue] function
  * and sets it using the given [setValue] function.
+ * [lazyValue] should be a pure function.
  */
 fun <T> mutableProvider(lazyValue: () -> T, setValue: (T) -> Unit = {}): MutableProvider<T> =
     mutableProvider(lazyValue).apply { subscribe(setValue) }

commons-provider/src/main/kotlin/xyz/xenondevs/commons/provider/CombinedMappingProviders.kt

@@ -9,6 +9,8 @@ import kotlin.concurrent.withLock
 /**
  * Creates and returns a new [Provider] that combines all values of [providers]
  * and immediately maps them to [R] using [mapValue].
+ * 
+ * [mapValue] should be a pure function.
  */
 @Suppress("UNCHECKED_CAST")
 fun <T, R> combinedProvider(providers: List<Provider<T>>, mapValue: (List<T>) -> R): Provider<R> =
@@ -17,6 +19,8 @@ fun <T, R> combinedProvider(providers: List<Provider<T>>, mapValue: (List<T>) ->
 /**
  * Creates and returns a new [Provider] that combines the values of [a] and [b]
  * and immediately maps them to [R] using [mapValue].
+ *
+ * [mapValue] should be a pure function.
  */
 fun <A, B, R> combinedProvider(
     a: Provider<A>,
@@ -32,6 +36,8 @@ fun <A, B, R> combinedProvider(
 /**
  * Creates and returns a new [Provider] that combines the values of [a], [b] and [c]
  * and immediately maps them to [R] using [mapValue].
+ *
+ * [mapValue] should be a pure function.
  */
 fun <A, B, C, R> combinedProvider(
     a: Provider<A>,
@@ -49,6 +55,8 @@ fun <A, B, C, R> combinedProvider(
 /**
  * Creates and returns a new [Provider] that combines the values of [a], [b], [c] and [d]
  * and immediately maps them to [R] using [mapValue].
+ *
+ * [mapValue] should be a pure function.
  */
 fun <A, B, C, D, R> combinedProvider(
     a: Provider<A>,
@@ -68,6 +76,8 @@ fun <A, B, C, D, R> combinedProvider(
 /**
  * Creates and returns a new [Provider] that combines the values of [a], [b], [c], [d] and [e]
  * and immediately maps them to [R] using [mapValue].
+ *
+ * [mapValue] should be a pure function.
  */
 fun <A, B, C, D, E, R> combinedProvider(
     a: Provider<A>,
@@ -89,6 +99,8 @@ fun <A, B, C, D, E, R> combinedProvider(
 /**
  * Creates and returns a new [Provider] that combines the values of [a], [b], [c], [d], [e] and [f]
  * and immediately maps them to [R] using [mapValue].
+ *
+ * [mapValue] should be a pure function.
  */
 fun <A, B, C, D, E, F, R> combinedProvider(
     a: Provider<A>,
@@ -112,6 +124,8 @@ fun <A, B, C, D, E, F, R> combinedProvider(
 /**
  * Creates and returns a new [Provider] that combines the values of [a], [b], [c], [d], [e], [f] and [g]
  * and immediately maps them to [R] using [mapValue].
+ *
+ * [mapValue] should be a pure function.
  */
 fun <A, B, C, D, E, F, G, R> combinedProvider(
     a: Provider<A>,
@@ -137,6 +151,8 @@ fun <A, B, C, D, E, F, G, R> combinedProvider(
 /**
  * Creates and returns a new [Provider] that combines the values of [a], [b], [c], [d], [e], [f], [g] and [h]
  * and immediately maps them to [R] using [mapValue].
+ *
+ * [mapValue] should be a pure function.
  */
 fun <A, B, C, D, E, F, G, H, R> combinedProvider(
     a: Provider<A>,
@@ -164,6 +180,8 @@ fun <A, B, C, D, E, F, G, H, R> combinedProvider(
 /**
  * Creates and returns a new [Provider] that combines the values of [a], [b], [c], [d], [e], [f], [g], [h] and [i]
  * and immediately maps them to [R] using [mapValue].
+ *
+ * [mapValue] should be a pure function.
  */
 fun <A, B, C, D, E, F, G, H, I, R> combinedProvider(
     a: Provider<A>,
@@ -193,6 +211,8 @@ fun <A, B, C, D, E, F, G, H, I, R> combinedProvider(
 /**
  * Creates and returns a new [Provider] that combines the values of [a], [b], [c], [d], [e], [f], [g], [h], [i] and [j]
  * and immediately maps them to [R] using [mapValue].
+ *
+ * [mapValue] should be a pure function.
  */
 fun <A, B, C, D, E, F, G, H, I, J, R> combinedProvider(
     a: Provider<A>,
@@ -225,6 +245,8 @@ fun <A, B, C, D, E, F, G, H, I, J, R> combinedProvider(
  * Creates and returns a new [Provider] that combines all values of [providers]
  * and immediately maps them to [R] using [mapValue].
  *
+ * [mapValue] should be a pure function.
+ *
  * The returned provider will only be stored in a [WeakReference] in the parent providers.
  */
 @Suppress("UNCHECKED_CAST")
@@ -235,6 +257,8 @@ fun <T, R> weakCombinedProvider(providers: List<Provider<T>>, mapValue: (List<T>
  * Creates and returns a new [Provider] that combines the values of [a] and [b]
  * and immediately maps them to [R] using [mapValue].
  *
+ * [mapValue] should be a pure function.
+ *
  * The returned provider will only be stored in a [WeakReference] in the parent providers.
  */
 fun <A, B, R> weakCombinedProvider(
@@ -252,6 +276,8 @@ fun <A, B, R> weakCombinedProvider(
  * Creates and returns a new [Provider] that combines the values of [a], [b] and [c]
  * and immediately maps them to [R] using [mapValue].
  *
+ * [mapValue] should be a pure function.
+ *
  * The returned provider will only be stored in a [WeakReference] in the parent providers.
  */
 fun <A, B, C, R> weakCombinedProvider(
@@ -271,6 +297,8 @@ fun <A, B, C, R> weakCombinedProvider(
  * Creates and returns a new [Provider] that combines the values of [a], [b], [c] and [d]
  * and immediately maps them to [R] using [mapValue].
  *
+ * [mapValue] should be a pure function.
+ *
  * The returned provider will only be stored in a [WeakReference] in the parent providers.
  */
 fun <A, B, C, D, R> weakCombinedProvider(
@@ -292,6 +320,8 @@ fun <A, B, C, D, R> weakCombinedProvider(
  * Creates and returns a new [Provider] that combines the values of [a], [b], [c], [d] and [e]
  * and immediately maps them to [R] using [mapValue].
  *
+ * [mapValue] should be a pure function.
+ *
  * The returned provider will only be stored in a [WeakReference] in the parent providers.
  */
 fun <A, B, C, D, E, R> weakCombinedProvider(
@@ -315,6 +345,8 @@ fun <A, B, C, D, E, R> weakCombinedProvider(
  * Creates and returns a new [Provider] that combines the values of [a], [b], [c], [d], [e] and [f]
  * and immediately maps them to [R] using [mapValue].
  *
+ * [mapValue] should be a pure function.
+ *
  * The returned provider will only be stored in a [WeakReference] in the parent providers.
  */
 fun <A, B, C, D, E, F, R> weakCombinedProvider(
@@ -340,6 +372,8 @@ fun <A, B, C, D, E, F, R> weakCombinedProvider(
  * Creates and returns a new [Provider] that combines the values of [a], [b], [c], [d], [e], [f] and [g]
  * and immediately maps them to [R] using [mapValue].
  *
+ * [mapValue] should be a pure function.
+ *
  * The returned provider will only be stored in a [WeakReference] in the parent providers.
  */
 fun <A, B, C, D, E, F, G, R> weakCombinedProvider(
@@ -367,6 +401,8 @@ fun <A, B, C, D, E, F, G, R> weakCombinedProvider(
  * Creates and returns a new [Provider] that combines the values of [a], [b], [c], [d], [e], [f], [g] and [h]
  * and immediately maps them to [R] using [mapValue].
  *
+ * [mapValue] should be a pure function.
+ *
  * The returned provider will only be stored in a [WeakReference] in the parent providers.
  */
 fun <A, B, C, D, E, F, G, H, R> weakCombinedProvider(
@@ -396,6 +432,8 @@ fun <A, B, C, D, E, F, G, H, R> weakCombinedProvider(
  * Creates and returns a new [Provider] that combines the values of [a], [b], [c], [d], [e], [f], [g], [h] and [i]
  * and immediately maps them to [R] using [mapValue].
  *
+ * [mapValue] should be a pure function.
+ *
  * The returned provider will only be stored in a [WeakReference] in the parent providers.
  */
 fun <A, B, C, D, E, F, G, H, I, R> weakCombinedProvider(
@@ -427,6 +465,8 @@ fun <A, B, C, D, E, F, G, H, I, R> weakCombinedProvider(
  * Creates and returns a new [Provider] that combines the values of [a], [b], [c], [d], [e], [f], [g], [h], [i] and [j]
  * and immediately maps them to [R] using [mapValue].
  *
+ * [mapValue] should be a pure function.
+ *
  * The returned provider will only be stored in a [WeakReference] in the parent providers.
  */
 fun <A, B, C, D, E, F, G, H, I, J, R> weakCombinedProvider(

commons-provider/src/main/kotlin/xyz/xenondevs/commons/provider/DefaultingProviders.kt

@@ -43,6 +43,8 @@ fun <T : Any> MutableProvider<T?>.weakDefaultsTo(provider: Provider<T>): Mutable
 /**
  * Creates a new [MutableProvider] that defaults to the value obtained through the [lazyValue] lambda if the value of [this][MutableProvider] is null.
  * The default value is propagated upwards when the value of the returned provider is loaded.
+ * 
+ * [lazyValue] should be a pure function.
  */
 fun <T : Any> MutableProvider<T?>.defaultsToLazily(lazyValue: () -> T): MutableProvider<T> =
     defaultsTo(provider(lazyValue))
@@ -51,6 +53,8 @@ fun <T : Any> MutableProvider<T?>.defaultsToLazily(lazyValue: () -> T): MutableP
  * Creates a new [MutableProvider] that defaults to the value obtained through the [lazyValue] lambda if the value of [this][MutableProvider] is null.
  * The default value is propagated upwards when the value of the returned provider is loaded.
  *
+ * [lazyValue] should be a pure function.
+ *
  * The returned provider will only be stored in a [WeakReference] in the parent provider ([this][MutableProvider]).
  */
 fun <T : Any> MutableProvider<T?>.weakDefaultsToLazily(lazyValue: () -> T): MutableProvider<T> =

commons-provider/src/main/kotlin/xyz/xenondevs/commons/provider/FallbackProviders.kt

@@ -49,27 +49,35 @@ private fun <T> Provider<T?>.orElse(provider: Provider<T>, weak: Boolean): Provi
 
 /**
  * Creates and returns a new [Provider] that returns a fallback value obtained through [provider] if the value of [this][Provider] is null.
+ *
+ * [lazyValue] should be a pure function.
  */
 fun <T> Provider<T?>.orElseLazily(lazyValue: () -> T): Provider<T> =
     orElse(provider(lazyValue))
 
 /**
  * Creates and returns a new [Provider] that returns a fallback value obtained through [provider] if the value of [this][Provider] is null.
  *
+ * [lazyValue] should be a pure function.
+ *
  * The returned provider will only be stored in a [WeakReference] in the parent provider ([this][MutableProvider]).
  */
 fun <T> Provider<T?>.weakOrElseLazily(lazyValue: () -> T): Provider<T> =
     weakOrElse(provider(lazyValue))
 
 /**
  * Creates a new [Provider] that returns a fallback value which is re-created through the [newValue] lambda every time the value of [this][Provider] is set to null.
+ *
+ * [newValue] should be a pure function.
  */
 fun <T> Provider<T?>.orElseNew(newValue: () -> T): Provider<T> =
     map { it ?: newValue() }
 
 /**
  * Creates a new [Provider] that returns a fallback value which is re-created through the [newValue] lambda every time the value of [this][Provider] is set to null.
  *
+ * [newValue] should be a pure function.
+ *
  * The returned provider will only be stored in a [WeakReference] in the parent provider ([this][MutableProvider]).
  */
 fun <T> Provider<T?>.weakOrElseNew(newValue: () -> T): Provider<T> =
@@ -119,6 +127,8 @@ fun <T : Any> MutableProvider<T?>.weakOrElse(provider: Provider<T>): MutableProv
  * Creates a new [MutableProvider] that returns a fallback value obtained through the [lazyValue] lambda if the value of [this][MutableProvider] is null.
  * Conversely, if the returned provider's value is set to a value equal to the one obtained through [lazyValue], the value of [this][MutableProvider] will be set to null.
  *
+ * [lazyValue] should be a pure function.
+ *
  * This function is fundamentally different from [MutableProvider.defaultsToLazily] as it does not pass the default value upwards.
  */
 fun <T : Any> MutableProvider<T?>.orElseLazily(lazyValue: () -> T): MutableProvider<T> =
@@ -128,6 +138,8 @@ fun <T : Any> MutableProvider<T?>.orElseLazily(lazyValue: () -> T): MutableProvi
  * Creates a new [MutableProvider] that returns a fallback value obtained through the [lazyValue] lambda if the value of [this][MutableProvider] is null.
  * Conversely, if the returned provider's value is set to a value equal to the one obtained through [lazyValue], the value of [this][MutableProvider] will be set to null.
  *
+ * [lazyValue] should be a pure function.
+ *
  * This function is fundamentally different from [MutableProvider.defaultsToLazily] as it does not pass the default value upwards.
  *
  * The returned provider will only be stored in a [WeakReference] in the parent provider ([this][MutableProvider]).
@@ -140,6 +152,8 @@ fun <T : Any> MutableProvider<T?>.weakOrElseLazily(lazyValue: () -> T): MutableP
  * Conversely, if the returned provider's value is set to a value equal to one returned by [newValue], the value of [this][MutableProvider] will be set to null.
  *
  * For mutable data types, it is required that the [newValue] lambda returns a new instance every time it is called, and that all of those instances are [equal][Any.equals] to each other.
+ *
+ * [newValue] should be a pure function.
  */
 fun <T : Any> MutableProvider<T?>.orElseNew(newValue: () -> T): MutableProvider<T> =
     MutableFallbackNewProvider(this as AbstractProvider<T?>, newValue, false)
@@ -150,6 +164,8 @@ fun <T : Any> MutableProvider<T?>.orElseNew(newValue: () -> T): MutableProvider<
  *
  * For mutable data types, it is required that the [newValue] lambda returns a new instance every time it is called, and that all of those instances are [equal][Any.equals] to each other.
  *
+ * [newValue] should be a pure function.
+ *
  * The returned provider will only be stored in a [WeakReference] in the parent provider ([this][MutableProvider]).
  */
 fun <T : Any> MutableProvider<T?>.weakOrElseNew(newValue: () -> T): MutableProvider<T> =