UpdatableLazy Kdocs

Author: Avanatiker

common/src/main/kotlin/com/lambda/util/collections/UpdatableLazy.kt

@@ -17,18 +17,55 @@
 
 package com.lambda.util.collections
 
+/**
+ * A lazy-initialized value holder that allows the stored value to be reset and re-initialized on demand.
+ *
+ * This class supports lazy initialization for a value of type [T] using a provided initializer function.
+ * Once the value is accessed, it is initialized and stored. The `update` function can be called to reset
+ * the value, allowing it to be re-initialized using the same initializer function.
+ *
+ * @param T The type of the value being lazily initialized and managed.
+ * @constructor Accepts an initializer function that defines how the value should be created.
+ */
 class UpdatableLazy<T>(private val initializer: () -> T) {
     private var _value: T? = null
 
+    /**
+     * Lazily initializes and retrieves a value of type [T] using the provided initializer function.
+     * If the value has not been initialized previously, the initializer function is called
+     * to generate the value, which is then cached for subsequent accesses.
+     *
+     * This property ensures that the value is only initialized when it is first accessed,
+     * and maintains its state until explicitly updated or reset.
+     *
+     * @return The lazily initialized value, or `null` if the initializer function
+     *         is designed to produce a `null` result or has not been called yet.
+     */
     val value: T?
         get() {
             if (_value == null) _value = initializer()
             return _value
         }
 
+    /**
+     * Resets the current value to a new value generated by the initializer function.
+     *
+     * This function effectively re-initializes the stored value by discarding the existing value,
+     * if any, and calling the initializer function to compute a new value.
+     * It is useful for scenarios where the lazily computed value needs to be refreshed or updated
+     * explicitly.
+     */
     fun update() {
         _value = initializer()
     }
 }
 
+/**
+ * Provides a lazily-initialized value that can be reset and re-initialized on demand.
+ * This function utilizes an `UpdatableLazy` to manage the lazy initialization and allow updates.
+ *
+ * @param T The type of the value to be lazily initialized.
+ * @param initializer A lambda function that defines how the value should be computed.
+ * @return An `UpdatableLazy` instance capable of managing a lazily-initialized value.
+ */
 fun <T> resettableLazy(initializer: () -> T) = UpdatableLazy(initializer)