Document extension functions in store.kt (#669)

Signed-off-by: Blake Oliveira <[email protected]>

Author: blakelee

store/src/commonMain/kotlin/org/mobilenativefoundation/store/store5/impl/extensions/store.kt

@@ -15,6 +15,19 @@ import org.mobilenativefoundation.store.store5.impl.RealStore
 /**
  * Helper factory that will return data for [key] if it is cached otherwise will return
  * fresh/network data (updating your caches)
+ *
+ * Note: Exceptions will not be handled within this function.
+ *
+ * ```
+ * try {
+ *   store.get<Key, Common>(Key.Read.All)
+ * } catch (e: Exception) {
+ *   // handle exception
+ * }
+ * ```
+ *
+ * @param Key The key to get cached data for.
+ * @param Output The common representation of the data.
  */
 suspend fun <Key : Any, Output : Any> Store<Key, Output>.get(key: Key) =
     stream(StoreReadRequest.cached(key, refresh = false))
@@ -25,17 +38,51 @@ suspend fun <Key : Any, Output : Any> Store<Key, Output>.get(key: Key) =
 /**
  * Helper factory that will return fresh data for [key] while updating your caches
  *
- * Note: If the [Fetcher] does not return any data (i.e the returned
- * [kotlinx.coroutines.Flow], when collected, is empty). Then store will fall back to local
+ * If the [Fetcher] does not return any data (i.e the returned
+ * [kotlinx.coroutines.flow.Flow], when collected, is empty). Then store will fall back to local
  * data **even** if you explicitly requested fresh data.
  * See https://github.com/dropbox/Store/pull/194 for context
+ *
+ * Note: Exceptions will not be handled within this function.
+ *
+ * ```
+ * try {
+ *   store.fresh<Key, Common>(Key.Read.All)
+ * } catch (e: Exception) {
+ *   // handle exception
+ * }
+ * ```
+ *
+ * @param Key The key to fetch fresh data for.
+ * @param Output The common representation of the data.
+ * @return The fresh data associated with the key.
  */
 suspend fun <Key : Any, Output : Any> Store<Key, Output>.fresh(key: Key) =
     stream(StoreReadRequest.fresh(key))
         .filterNot { it is StoreReadResponse.Loading || it is StoreReadResponse.NoNewData }
         .first()
         .requireData()
 
+/**
+ * Extension function to convert a [Store] into a [MutableStore].
+ *
+ * This function allows a [Store] to be used as a [MutableStore] by providing an [Updater] and an
+ * optional [Bookkeeper].
+ *
+ * ```
+ * store.asMutableStore<Key, Dto, Common, Entity, WriteResponse>(updater, bookkeeper)
+ * ```
+ *
+ * @param Key The type of the key used to get data.
+ * @param Network The type of data returned by the fetcher
+ * @param Output The common representation of the data.
+ * @param Local The type of the data used by the source of truth.
+ * @param Response The updater result write response type.
+ * @param updater Posts data to remote data source.
+ * @param bookkeeper Optionally used to track when local changes fail to sync with network.
+ * @return A [MutableStore] instance.
+ * @throws Exception if the [Store] is not built using [StoreBuilder].
+ */
 @OptIn(ExperimentalStoreApi::class)
 @Suppress("UNCHECKED_CAST")
 fun <Key : Any, Network : Any, Output : Any, Local : Any, Response : Any> Store<Key, Output>.asMutableStore(
@@ -53,13 +100,54 @@ fun <Key : Any, Network : Any, Output : Any, Local : Any, Response : Any> Store<
     )
 }
 
+/**
+ * Helper function that returns data for the given [key] if it is cached, otherwise it will return
+ * fresh/network data (updating your caches).
+ *
+ * Note: Exceptions will not be handled within this function.
+ *
+ * ```
+ * try {
+ *   store.get<Key, Common, WriteResponse>(Key.Read.All)
+ * } catch (e: Exception) {
+ *   // handle exception
+ * }
+ * ```
+ *
+ * @param Key The key to get cached data for.
+ * @param Output The common representation of the data.
+ * @param Response The updater result write response type.
+ * @return The data associated with the key.
+ */
 @OptIn(ExperimentalStoreApi::class)
 suspend fun <Key : Any, Output : Any, Response : Any> MutableStore<Key, Output>.get(key: Key) =
     stream<Response>(StoreReadRequest.cached(key, refresh = false))
         .filterNot { it is StoreReadResponse.Loading || it is StoreReadResponse.NoNewData }
         .first()
         .requireData()
 
+/**
+ * Helper function that returns fresh data for the given [key] while updating your caches.
+ *
+ * If the [Fetcher] does not return any data (i.e., the returned [kotlinx.coroutines.flow.Flow],
+ * when collected, is empty), then the store will fall back to local data even if you explicitly
+ * requested fresh data.
+ *
+ * Note: Exceptions will not be handled within this function.
+ *
+ * ```
+ * try {
+ *   store.fresh<Key, Common, WriteResponse>(Key.Read.All)
+ * } catch (e: Exception) {
+ *   // handle exception
+ * }
+ * ```
+ *
+ * @param Key The key to fetch fresh data for.
+ * @param Output The common representation of the data.
+ * @param Response The updater result write response type.
+ * @return The fresh data associated with the key.
+ */
 @OptIn(ExperimentalStoreApi::class)
 suspend fun <Key : Any, Output : Any, Response : Any> MutableStore<Key, Output>.fresh(key: Key) =
     stream<Response>(StoreReadRequest.fresh(key))