Document invui-kotlin reactive api functions

Author: NichtStudioCode

invui-kotlin/src/main/kotlin/xyz/xenondevs/invui/PropertyWrappers.kt renamed to invui-kotlin/src/main/kotlin/xyz/xenondevs/invui/PropertyAdapter.kt

@@ -49,14 +49,27 @@ operator fun Gui.plusAssign(elements: Iterable<SlotElement>) = elements.forEach
 @JvmName("plusAssignItems")
 operator fun Gui.plusAssign(items: Iterable<Item>) = items.forEach { addItems(it) }
 
+/**
+ * Sets the provider containing the background [ItemProvider] for the [Gui] built by this builder.
+ * If [background] is not a [MutableProvider] attempting to change the background through other means will throw an exception.
+ */
 @ExperimentalReactiveApi
-fun <G : Gui, B : Gui.Builder<G, B>> B.setBackground(provider: Provider<ItemProvider?>): B =
-    setBackground(PropertyAdapter(provider))
+fun <G : Gui, B : Gui.Builder<G, B>> B.setBackground(background: Provider<ItemProvider?>): B =
+    setBackground(PropertyAdapter(background))
 
+/**
+ * Sets the provider containing the frozen state of the [Gui] built by this builder.
+ * If [frozen] is not a [MutableProvider] attempting to change the frozen state through other means will throw an exception.
+ */
 @ExperimentalReactiveApi
-fun <G : Gui, B : Gui.Builder<G, B>> B.setFrozen(provider: Provider<Boolean>): B =
-    setFrozen(PropertyAdapter(provider))
+fun <G : Gui, B : Gui.Builder<G, B>> B.setFrozen(frozen: Provider<Boolean>): B =
+    setFrozen(PropertyAdapter(frozen))
 
+/**
+ * Sets the provider containing the setting whether slots of partially obscured embedded inventories
+ * should be ignored or not of the [Gui] built by this builder.
+ * If the provider is not a [MutableProvider], attempting to change this setting through other means will throw an exception.
+ */
 @ExperimentalReactiveApi
-fun <G : Gui, B : Gui.Builder<G, B>> B.setIgnoreObscuredInventorySlots(provider: Provider<Boolean>): B =
-    setIgnoreObscuredInventorySlots(PropertyAdapter(provider))
+fun <G : Gui, B : Gui.Builder<G, B>> B.setIgnoreObscuredInventorySlots(ignoreObscuredInventorySlots: Provider<Boolean>): B =
+    setIgnoreObscuredInventorySlots(PropertyAdapter(ignoreObscuredInventorySlots))

invui-kotlin/src/main/kotlin/xyz/xenondevs/invui/gui/GuiExtensions.kt

@@ -5,14 +5,27 @@ import xyz.xenondevs.commons.provider.Provider
 import xyz.xenondevs.invui.ExperimentalReactiveApi
 import xyz.xenondevs.invui.PropertyAdapter
 
+/**
+ * Sets the provider containing the current page for the [PagedGui] built by this builder.
+ * If the value of [page] is set to an invalid page, it will be automatically adjusted to the closest valid page.
+ */
 @ExperimentalReactiveApi
-fun <C : Any> PagedGui.Builder<C>.setPage(provider: MutableProvider<Int>): PagedGui.Builder<C> =
-    setPage(PropertyAdapter(provider))
+fun <C : Any> PagedGui.Builder<C>.setPage(page: MutableProvider<Int>): PagedGui.Builder<C> =
+    setPage(PropertyAdapter(page))
 
+/**
+ * Sets the provider containing the content of the [PagedGui] built by this builder to the result
+ * of applying [transform] to the value of [provider].
+ * (Shortcut for `setContent(provider.map(transform))`)
+ */
 @ExperimentalReactiveApi
 fun <C : Any, T> PagedGui.Builder<C>.setContent(provider: Provider<T>, transform: (T) -> List<C>): PagedGui.Builder<C> =
     setContent(provider.map(transform))
 
+/**
+ * Sets the provider containing the content of the [PagedGui] built by this builder.
+ * If [content] is not a [MutableProvider], attempting to change the content through other means will throw an exception.
+ */
 @ExperimentalReactiveApi
-fun <C : Any> PagedGui.Builder<C>.setContent(provider: Provider<List<C>>): PagedGui.Builder<C> =
-    setContent(PropertyAdapter(provider))
+fun <C : Any> PagedGui.Builder<C>.setContent(content: Provider<List<C>>): PagedGui.Builder<C> =
+    setContent(PropertyAdapter(content))

invui-kotlin/src/main/kotlin/xyz/xenondevs/invui/gui/PagedGuiExtensions.kt

@@ -5,14 +5,27 @@ import xyz.xenondevs.commons.provider.Provider
 import xyz.xenondevs.invui.ExperimentalReactiveApi
 import xyz.xenondevs.invui.PropertyAdapter
 
+/**
+ * Sets the provider containing the current line for the [ScrollGui] built by this builder.
+ * If the value of [line] is set to an invalid line, it will be automatically adjusted to the closest valid line.
+ */
 @ExperimentalReactiveApi
-fun <C : Any> ScrollGui.Builder<C>.setLine(provider: MutableProvider<Int>): ScrollGui.Builder<C> =
-    setLine(PropertyAdapter(provider))
+fun <C : Any> ScrollGui.Builder<C>.setLine(line: MutableProvider<Int>): ScrollGui.Builder<C> =
+    setLine(PropertyAdapter(line))
 
+/**
+ * Sets the provider containing the content of the [ScrollGui] built by this builder to the result
+ * of applying [transform] to the value of [provider].
+ * (Shortcut for `setContent(provider.map(transform))`)
+ */
 @ExperimentalReactiveApi
 fun <C : Any, T> ScrollGui.Builder<C>.setContent(provider: Provider<T>, transform: (T) -> List<C>): ScrollGui.Builder<C> =
     setContent(provider.map(transform))
 
+/**
+ * Sets the provider containing the content of the [ScrollGui] built by this builder.
+ * If [content] is not a [MutableProvider], attempting to change the content through other means will throw an exception.
+ */
 @ExperimentalReactiveApi
-fun <C : Any> ScrollGui.Builder<C>.setContent(provider: Provider<List<C>>): ScrollGui.Builder<C> =
-    setContent(PropertyAdapter(provider))
+fun <C : Any> ScrollGui.Builder<C>.setContent(content: Provider<List<C>>): ScrollGui.Builder<C> =
+    setContent(PropertyAdapter(content))

invui-kotlin/src/main/kotlin/xyz/xenondevs/invui/gui/ScrollGuiExtensions.kt

@@ -5,14 +5,27 @@ import xyz.xenondevs.commons.provider.Provider
 import xyz.xenondevs.invui.ExperimentalReactiveApi
 import xyz.xenondevs.invui.PropertyAdapter
 
+/**
+ * Sets the provider containing the current tab for the [TabGui] built by this builder.
+ * If the value of [tab] is set to an invalid tab, it will be automatically adjusted to the closest valid tab.
+ */
 @ExperimentalReactiveApi
-fun TabGui.Builder.setTab(provider: MutableProvider<Int>): TabGui.Builder =
-    setTab(PropertyAdapter(provider))
+fun TabGui.Builder.setTab(tab: MutableProvider<Int>): TabGui.Builder =
+    setTab(PropertyAdapter(tab))
 
+/**
+ * Sets the provider containing the tabs of the [TabGui] built by this builder to the result
+ * of applying [transform] to the value of [provider].
+ * (Shortcut for `setTabs(provider.map(transform))`)
+ */
 @ExperimentalReactiveApi
 fun <T> TabGui.Builder.setTabs(provider: Provider<T>, transform: (T) -> List<Gui?>): TabGui.Builder =
     setTabs(provider.map(transform))
 
+/**
+ * Sets the tabs containing the tabs of the [TabGui] built by this builder.
+ * If [tabs] is not a [MutableProvider], attempting to change the tabs through other means will throw an exception.
+ */
 @ExperimentalReactiveApi
-fun TabGui.Builder.setTabs(provider: Provider<List<Gui?>>): TabGui.Builder =
-    setTabs(PropertyAdapter(provider))
+fun TabGui.Builder.setTabs(tabs: Provider<List<Gui?>>): TabGui.Builder =
+    setTabs(PropertyAdapter(tabs))

invui-kotlin/src/main/kotlin/xyz/xenondevs/invui/gui/TabGuiExtensions.kt

@@ -12,11 +12,19 @@ import kotlin.experimental.ExperimentalTypeInference
  */
 fun Iterable<Item>.notifyWindows() = forEach { it.notifyWindows() }
 
+/**
+ * Sets the [Provider] containing the [ItemProvider] for the [Item] built by this builder to the result
+ * of applying [transform] to the value of [provider].
+ * (Shortcut for `setItemProvider(provider.map(transform))`)
+ */
 @OverloadResolutionByLambdaReturnType
 @ExperimentalReactiveApi
 fun <S : Item.Builder<*>, T> S.setItemProvider(provider: Provider<T>, transform: (T) -> ItemProvider) =
     setItemProvider(provider.map(transform))
 
+/**
+ * Sets the [provider] containing the [ItemProvider] for the [Item] built by this builder.
+ */
 @ExperimentalReactiveApi
 fun <S : Item.Builder<*>> S.setItemProvider(
     provider: Provider<ItemProvider>
@@ -26,11 +34,20 @@ fun <S : Item.Builder<*>> S.setItemProvider(
     return this
 }
 
+/**
+ * Sets the [Provider] containing the [ItemStack] for the [Item] built by this builder to the result
+ * of applying [transform] to the value of [provider].
+ * (Shortcut for `setItemProvider(provider.map(transform))`)
+ */
 @JvmName("setItemProvider1")
 @ExperimentalReactiveApi
 fun <S : Item.Builder<*>, T> S.setItemProvider(provider: Provider<T>, transform: (T) -> ItemStack) =
     setItemProvider(provider.map(transform))
 
+/**
+ * Sets the [provider] containing the [ItemStack] for the [Item] built by this builder.
+ * (Shortcut for `setItemProvider(provider.map(::ItemWrapper))`)
+ */
 @JvmName("setItemProvider1")
 @ExperimentalReactiveApi
 fun <S : Item.Builder<*>> S.setItemProvider(

invui-kotlin/src/main/kotlin/xyz/xenondevs/invui/item/ItemExtensions.kt

@@ -5,23 +5,44 @@ import xyz.xenondevs.commons.provider.Provider
 import xyz.xenondevs.invui.ExperimentalReactiveApi
 import xyz.xenondevs.invui.PropertyAdapter
 
-@Suppress("UNCHECKED_CAST")
+/**
+ * Adds [handler] as a rename handler for the [AnvilWindow] built by this builder,
+ * meaning the anvil text field will be written into [handler].
+ */
 @ExperimentalReactiveApi
 fun AnvilWindow.Builder.addRenameHandler(handler: MutableProvider<String>): AnvilWindow.Builder =
     addRenameHandler(handler::set)
 
+/**
+ * Sets the provider containing the setting whether the text field of the [AnvilWindow] built by this builder is always enabled
+ * to the result of applying [transform] to the value of [provider].
+ * (Shortcut for `setTextFieldAlwaysEnabled(provider.map(transform))`)
+ */
 @ExperimentalReactiveApi
 fun <T> AnvilWindow.Builder.setTextFieldAlwaysEnabled(provider: Provider<T>, transform: (T) -> Boolean): AnvilWindow.Builder =
     setTextFieldAlwaysEnabled(provider.map(transform))
 
+/**
+ * Sets the provider containing the setting whether the text field of the [AnvilWindow] built by this builder is always enabled.
+ * If [textFieldAlwaysEnabled] is not a [MutableProvider], attempting to change the setting through other means will throw an exception.
+ */
 @ExperimentalReactiveApi
-fun AnvilWindow.Builder.setTextFieldAlwaysEnabled(enabled: Provider<Boolean>): AnvilWindow.Builder =
-    setTextFieldAlwaysEnabled(PropertyAdapter(enabled))
+fun AnvilWindow.Builder.setTextFieldAlwaysEnabled(textFieldAlwaysEnabled: Provider<Boolean>): AnvilWindow.Builder =
+    setTextFieldAlwaysEnabled(PropertyAdapter(textFieldAlwaysEnabled))
 
+/**
+ * Sets the provider containing the setting whether the result of the [AnvilWindow] built by this builder is always valid
+ * to the result of applying [transform] to the value of [provider].
+ * (Shortcut for `setResultAlwaysValid(provider.map(transform))`)
+ */
 @ExperimentalReactiveApi
 fun <T> AnvilWindow.Builder.setResultAlwaysValid(provider: Provider<T>, transform: (T) -> Boolean): AnvilWindow.Builder =
     setResultAlwaysValid(provider.map(transform))
 
+/**
+ * Sets the provider containing the setting whether the result of the [AnvilWindow] built by this builder is always valid.
+ * If [resultAlwaysValid] is not a [MutableProvider], attempting to change the setting through other means will throw an exception.
+ */
 @ExperimentalReactiveApi
-fun AnvilWindow.Builder.setResultAlwaysValid(enabled: Provider<Boolean>): AnvilWindow.Builder =
-    setResultAlwaysValid(PropertyAdapter(enabled))
+fun AnvilWindow.Builder.setResultAlwaysValid(resultAlwaysValid: Provider<Boolean>): AnvilWindow.Builder =
+    setResultAlwaysValid(PropertyAdapter(resultAlwaysValid))

invui-kotlin/src/main/kotlin/xyz/xenondevs/invui/window/AnvilWindowExtensions.kt

@@ -1,21 +1,40 @@
 package xyz.xenondevs.invui.window
 
+import xyz.xenondevs.commons.provider.MutableProvider
 import xyz.xenondevs.commons.provider.Provider
 import xyz.xenondevs.invui.ExperimentalReactiveApi
 import xyz.xenondevs.invui.PropertyAdapter
 
+/**
+ * Sets the provider containing the [brew progress][BrewingWindow.Builder.setBrewProgress] of the [BrewingWindow] built by this builder
+ * to the result of applying [transform] to the value of [provider].
+ * (Shortcut for `setBrewProgress(provider.map(transform))`)
+ */
 @ExperimentalReactiveApi
 fun <T> BrewingWindow.Builder.setBrewProgress(provider: Provider<T>, transform: (T) -> Double): BrewingWindow.Builder =
     setBrewProgress(provider.map(transform))
 
+/**
+ * Sets the provider containing the [brew progress][BrewingWindow.Builder.setBrewProgress] of the [BrewingWindow] built by this builder.
+ * If [brewProgress] is not a [MutableProvider], attempting to change the brew progress through other means will throw an exception.
+ */
 @ExperimentalReactiveApi
-fun BrewingWindow.Builder.setBrewProgress(progress: Provider<Double>): BrewingWindow.Builder =
-    setBrewProgress(PropertyAdapter(progress))
+fun BrewingWindow.Builder.setBrewProgress(brewProgress: Provider<Double>): BrewingWindow.Builder =
+    setBrewProgress(PropertyAdapter(brewProgress))
 
+/**
+ * Sets the provider containing the [fuel progress][BrewingWindow.Builder.setFuelProgress] of the [BrewingWindow] built by this builder
+ * to the result of applying [transform] to the value of [provider].
+ * (Shortcut for `setFuelProgress(provider.map(transform))`)
+ */
 @ExperimentalReactiveApi
 fun <T> BrewingWindow.Builder.setFuelProgress(provider: Provider<T>, transform: (T) -> Double): BrewingWindow.Builder =
     setFuelProgress(provider.map(transform))
 
+/**
+ * Sets the provider containing the [fuel progress][BrewingWindow.Builder.setFuelProgress] of the [BrewingWindow] built by this builder.
+ * If [fuelProgress] is not a [MutableProvider], attempting to change the fuel progress through other means will throw an exception.
+ */
 @ExperimentalReactiveApi
-fun BrewingWindow.Builder.setFuelProgress(progress: Provider<Double>): BrewingWindow.Builder =
-    setFuelProgress(PropertyAdapter(progress))
+fun BrewingWindow.Builder.setFuelProgress(fuelProgress: Provider<Double>): BrewingWindow.Builder =
+    setFuelProgress(PropertyAdapter(fuelProgress))

invui-kotlin/src/main/kotlin/xyz/xenondevs/invui/window/BrewingWindowExtensions.kt

@@ -1,21 +1,40 @@
 package xyz.xenondevs.invui.window
 
+import xyz.xenondevs.commons.provider.MutableProvider
 import xyz.xenondevs.commons.provider.Provider
 import xyz.xenondevs.invui.ExperimentalReactiveApi
 import xyz.xenondevs.invui.PropertyAdapter
 
+/**
+ * Sets the provider containing the icons on the map of the [CartographyWindow] built by this builder to the result
+ * of applying [transform] to the value of [provider].
+ * (Shortcut for `setIcons(provider.map(transform))`)
+ */
 @ExperimentalReactiveApi
 fun <T> CartographyWindow.Builder.setIcons(provider: Provider<T>, transform: (T) -> Set<CartographyWindow.MapIcon>): CartographyWindow.Builder =
     setIcons(provider.map(transform))
 
+/**
+ * Sets the provider containing the icons on the map of the [CartographyWindow] built by this builder.
+ * If [icons] is not a [MutableProvider], attempting to change the icons through other means will throw an exception.
+ */
 @ExperimentalReactiveApi
 fun CartographyWindow.Builder.setIcons(icons: Provider<Set<CartographyWindow.MapIcon>>): CartographyWindow.Builder =
     setIcons(PropertyAdapter(icons))
 
+/**
+ * Sets the provider containing the view of the [CartographyWindow] built by this builder to the result
+ * of applying [transform] to the value of [provider].
+ * (Shortcut for `setView(provider.map(transform))`)
+ */
 @ExperimentalReactiveApi
 fun <T> CartographyWindow.Builder.setView(provider: Provider<T>, transform: (T) -> CartographyWindow.View): CartographyWindow.Builder =
     setView(provider.map(transform))
 
+/**
+ * Sets the provider containing the view of the [CartographyWindow] built by this builder.
+ * If [view] is not a [MutableProvider], attempting to change the view through other means will throw an exception.
+ */
 @ExperimentalReactiveApi
 fun CartographyWindow.Builder.setView(view: Provider<CartographyWindow.View>): CartographyWindow.Builder =
     setView(PropertyAdapter(view))

invui-kotlin/src/main/kotlin/xyz/xenondevs/invui/window/CartographyWindowExtensions.kt

@@ -5,18 +5,30 @@ import xyz.xenondevs.invui.ExperimentalReactiveApi
 import xyz.xenondevs.invui.PropertyAdapter
 import xyz.xenondevs.invui.gui.Slot
 
+/**
+ * Sets the provider containing the disabled state of [slot] in the [CrafterWindow] built by this builder.
+ */
 @ExperimentalReactiveApi
-fun CrafterWindow.Builder.setSlot(slot: Int, provider: MutableProvider<Boolean>): CrafterWindow.Builder =
-    setSlot(slot, PropertyAdapter(provider))
+fun CrafterWindow.Builder.setSlot(slot: Int, state: MutableProvider<Boolean>): CrafterWindow.Builder =
+    setSlot(slot, PropertyAdapter(state))
 
+/**
+ * Sets the provider containing the disabled state of the slot at [x], [y] in the [CrafterWindow] built by this builder.
+ */
 @ExperimentalReactiveApi
-fun CrafterWindow.Builder.setSlot(x: Int, y: Int, provider: MutableProvider<Boolean>): CrafterWindow.Builder =
-    setSlot(x, y, PropertyAdapter(provider))
+fun CrafterWindow.Builder.setSlot(x: Int, y: Int, state: MutableProvider<Boolean>): CrafterWindow.Builder =
+    setSlot(x, y, PropertyAdapter(state))
 
+/**
+ * Sets the provider containing the disabled state of [slot] in the [CrafterWindow] built by this builder.
+ */
 @ExperimentalReactiveApi
-fun CrafterWindow.Builder.setSlot(slot: Slot, provider: MutableProvider<Boolean>): CrafterWindow.Builder =
-    setSlot(slot, PropertyAdapter(provider))
+fun CrafterWindow.Builder.setSlot(slot: Slot, state: MutableProvider<Boolean>): CrafterWindow.Builder =
+    setSlot(slot, PropertyAdapter(state))
 
+/**
+ * Sets the providers containing the disabled states of all nine slots in the [CrafterWindow] built by this builder.
+ */
 @ExperimentalReactiveApi
-fun CrafterWindow.Builder.setSlots(slots: List<MutableProvider<Boolean>>): CrafterWindow.Builder =
-    setSlots(slots.map { PropertyAdapter(it) })
+fun CrafterWindow.Builder.setSlots(states: List<MutableProvider<Boolean>>): CrafterWindow.Builder =
+    setSlots(states.map { PropertyAdapter(it) })