Merge pull request #691 from pylonmc/idra/docs-improvements

Docs improvements

Author: LordIdra

rebar/src/main/kotlin/io/github/pylonmc/rebar/Rebar.kt

@@ -178,7 +178,7 @@ object Rebar : JavaPlugin(), RebarAddon {
         RebarGrowable.register(this, pm)
         RebarCauldron.register(this, pm)
         RebarSign.register(this, pm)
-        RebarTrialVault.register(this, pm)
+        RebarVault.register(this, pm)
         RebarLeaf.register(this, pm)
         RebarTargetBlock.register(this, pm)
         RebarComposter.register(this, pm)
@@ -188,7 +188,7 @@ object Rebar : JavaPlugin(), RebarAddon {
         RebarEnchantingTable.register(this, pm)
         RebarRedstoneBlock.register(this, pm)
         RebarInteractBlock.register(this, pm)
-        RebarSneakableBlock.register(this, pm)
+        RebarSneakBlock.register(this, pm)
         RebarJobBlock.register(this, pm)
         RebarJumpBlock.register(this, pm)
         RebarUnloadBlock.register(this, pm)

rebar/src/main/kotlin/io/github/pylonmc/rebar/block/BlockStorage.kt

@@ -215,15 +215,15 @@ object BlockStorage : Listener {
 
     /**
      * Returns whether the block at [block] is a Rebar block.
-     * Returns false if the chunk at [blockPosition] is not loaded.
+     * Returns false if the chunk at [block] is not loaded.
      */
     @JvmStatic
     fun isRebarBlock(block: Block): Boolean =
         (block.position.chunk.isLoaded) && get(block) != null
 
     /**
      * Returns whether the block at [location] is a Rebar block
-     * Returns false if the chunk at [blockPosition] is not loaded.
+     * Returns false if the chunk at [location] is not loaded.
      */
     @JvmStatic
     fun isRebarBlock(location: Location): Boolean =

rebar/src/main/kotlin/io/github/pylonmc/rebar/block/base/RebarBeacon.kt

@@ -12,6 +12,7 @@ import io.papermc.paper.event.block.BeaconActivatedEvent
 import io.papermc.paper.event.block.BeaconDeactivatedEvent
 import io.papermc.paper.event.player.PlayerChangeBeaconEffectEvent
 import org.bukkit.event.EventPriority
+import org.jetbrains.annotations.ApiStatus
 
 @Suppress("unused")
 interface RebarBeacon {
@@ -20,6 +21,7 @@ interface RebarBeacon {
     fun onEffectChange(event: PlayerChangeBeaconEffectEvent, priority: EventPriority) {}
     fun onEffectApply(event: BeaconEffectEvent, priority: EventPriority) {}
 
+    @ApiStatus.Internal
     companion object : MultiListener {
         @UniversalHandler
         private fun onBeaconActivate(event: BeaconActivatedEvent, priority: EventPriority) {

rebar/src/main/kotlin/io/github/pylonmc/rebar/block/base/RebarBell.kt

@@ -9,11 +9,13 @@ import io.github.pylonmc.rebar.event.api.annotation.UniversalHandler
 import org.bukkit.event.EventPriority
 import org.bukkit.event.block.BellResonateEvent
 import org.bukkit.event.block.BellRingEvent
+import org.jetbrains.annotations.ApiStatus
 
 interface RebarBell {
     fun onRing(event: BellRingEvent, priority: EventPriority) {}
     fun onResonate(event: BellResonateEvent, priority: EventPriority) {}
 
+    @ApiStatus.Internal
     companion object : MultiListener {
         @UniversalHandler
         private fun onBellRing(event: BellRingEvent, priority: EventPriority) {

rebar/src/main/kotlin/io/github/pylonmc/rebar/block/base/RebarBreakHandler.kt

@@ -5,25 +5,34 @@ import org.bukkit.event.block.BlockBreakEvent
 import org.bukkit.inventory.ItemStack
 
 interface RebarBreakHandler {
+
     /**
      * Called before the block is broken. Note this is not called for [Deletions][BlockBreakContext.Delete]
      * as those are not cancellable.
      *
-     * In the case of a vanilla [BlockBreakEvent] this is called at the lowest priority
+     * In the case of a vanilla [BlockBreakEvent] this is called at the lowest priority.
      *
-     * @return If the block should be broken. If false, the break is cancelled.
+     * @return True if the block should be broken, false if the block break should be cancelled.
      */
     fun preBreak(context: BlockBreakContext): Boolean {
         return true
     }
 
     /**
-     * In the case of a vanilla [BlockBreakEvent] this is called during the monitor priority
+     * Called as the block is being broken. At this point, the block break cannot be
+     * cancelled, but the physical block has not yet been broken or removed from [io.github.pylonmc.rebar.block.BlockStorage].
+     *
+     * The main purpose of this is method to allow the block drops to be modified.
+     *
+     * In the case of a vanilla [BlockBreakEvent] this is called during the monitor priority.
      */
     fun onBreak(drops: MutableList<ItemStack>, context: BlockBreakContext) {}
 
     /**
-     * In the case of a vanilla [BlockBreakEvent] this is called during the monitor priority
+     * Called after the block has been broken. At this point, the block has been physically
+     * removed, block drops have been dropped, and the block has been removed from [io.github.pylonmc.rebar.block.BlockStorage].
+     *
+     * In the case of a vanilla [BlockBreakEvent] this is called during the monitor priority.
      */
     fun postBreak(context: BlockBreakContext) {}
 }

rebar/src/main/kotlin/io/github/pylonmc/rebar/block/base/RebarBrewingStand.kt

@@ -10,12 +10,14 @@ import org.bukkit.event.EventPriority
 import org.bukkit.event.block.BlockCookEvent
 import org.bukkit.event.block.InventoryBlockStartEvent
 import org.bukkit.event.inventory.BrewingStandFuelEvent
+import org.jetbrains.annotations.ApiStatus
 
 interface RebarBrewingStand {
     fun onStartBrewing(event: InventoryBlockStartEvent, priority: EventPriority) {}
     fun onFuel(event: BrewingStandFuelEvent, priority: EventPriority) {}
     fun onEndBrewing(event: BlockCookEvent, priority: EventPriority) {}
 
+    @ApiStatus.Internal
     companion object : MultiListener {
         @UniversalHandler
         private fun onStartCook(event: InventoryBlockStartEvent, priority: EventPriority) {

rebar/src/main/kotlin/io/github/pylonmc/rebar/block/base/RebarCampfire.kt

@@ -9,11 +9,13 @@ import io.github.pylonmc.rebar.event.api.annotation.UniversalHandler
 import org.bukkit.event.EventPriority
 import org.bukkit.event.block.BlockCookEvent
 import org.bukkit.event.block.InventoryBlockStartEvent
+import org.jetbrains.annotations.ApiStatus
 
 interface RebarCampfire {
     fun onStartCooking(event: InventoryBlockStartEvent, priority: EventPriority) {}
     fun onEndCooking(event: BlockCookEvent, priority: EventPriority) {}
 
+    @ApiStatus.Internal
     companion object : MultiListener {
         @UniversalHandler
         private fun onStartCook(event: InventoryBlockStartEvent, priority: EventPriority) {

rebar/src/main/kotlin/io/github/pylonmc/rebar/block/base/RebarCargoBlock.kt

@@ -33,10 +33,10 @@ import kotlin.math.min
 
 /**
  * Represents a block that can connect to cargo ducts and use them to interface
- * with other cargo RebarCargoBlocks.
+ * with other RebarCargoBlocks.
  *
- * Each face can have one logistic group which cargo ducts connected to that face
- * are allowed to interface with
+ * Each face can have one logistic group which cargo ducts (or other RebarCargoBlocks)
+ * connected to that face are allowed to interface with.
  *
  * In your place constructor, you will need to call [addCargoLogisticGroup] for all
  * the block faces you want to be able to connect cargo ducts to, and also
@@ -53,7 +53,7 @@ interface RebarCargoBlock : RebarLogisticBlock, RebarEntityHolderBlock {
 
     @ApiStatus.NonExtendable
     fun addCargoLogisticGroup(face: BlockFace, group: String) {
-        cargoBlockData.groups.put(face, group)
+        cargoBlockData.groups[face] = group
     }
 
     @ApiStatus.NonExtendable
@@ -84,15 +84,17 @@ interface RebarCargoBlock : RebarLogisticBlock, RebarEntityHolderBlock {
         @ApiStatus.NonExtendable
         get() = cargoBlockData.transferRate
 
+    @ApiStatus.NonExtendable
     fun onDuctConnected(event: RebarCargoConnectEvent, priority: EventPriority) {}
 
+    @ApiStatus.NonExtendable
     fun onDuctDisconnected(event: RebarCargoDisconnectEvent, priority: EventPriority) {}
 
     /**
      * Checks if the block can connect to any adjacent cargo blocks, and if so, creates
      * a duct display between this block and the adjacent cargo block in question.
      */
-    @ApiStatus.NonExtendable
+    @ApiStatus.Internal
     fun updateDirectlyConnectedFaces() {
         for (face in IMMEDIATE_FACES) {
             // We iterate IMMEDIATE_FACES instead of [cargoBlockData.groups] in case [cargoBlockData.groups] is
@@ -127,6 +129,7 @@ interface RebarCargoBlock : RebarLogisticBlock, RebarEntityHolderBlock {
         }
     }
 
+    @ApiStatus.Internal
     fun tickCargo() {
         for ((face, group) in cargoBlockData.groups) {
             val sourceGroup = getLogisticGroup(group)
@@ -149,6 +152,7 @@ interface RebarCargoBlock : RebarLogisticBlock, RebarEntityHolderBlock {
         }
     }
 
+    @ApiStatus.Internal
     fun tickCargoFace(sourceGroup: LogisticGroup, targetGroup: LogisticGroup) {
         for (sourceSlot in sourceGroup.slots) {
             val sourceStack = sourceSlot.getItemStack()

rebar/src/main/kotlin/io/github/pylonmc/rebar/block/base/RebarCauldron.kt

@@ -8,10 +8,12 @@ import io.github.pylonmc.rebar.event.api.annotation.MultiHandlers
 import io.github.pylonmc.rebar.event.api.annotation.UniversalHandler
 import org.bukkit.event.EventPriority
 import org.bukkit.event.block.CauldronLevelChangeEvent
+import org.jetbrains.annotations.ApiStatus
 
 interface RebarCauldron {
     fun onLevelChange(event: CauldronLevelChangeEvent, priority: EventPriority) {}
 
+    @ApiStatus.Internal
     companion object : MultiListener {
         @UniversalHandler
         private fun onCauldronLevelChange(event: CauldronLevelChangeEvent, priority: EventPriority) {

rebar/src/main/kotlin/io/github/pylonmc/rebar/block/base/RebarComposter.kt

@@ -9,11 +9,13 @@ import io.github.pylonmc.rebar.event.api.annotation.UniversalHandler
 import io.papermc.paper.event.block.CompostItemEvent
 import io.papermc.paper.event.entity.EntityCompostItemEvent
 import org.bukkit.event.EventPriority
+import org.jetbrains.annotations.ApiStatus
 
 interface RebarComposter {
     fun onCompostByHopper(event: CompostItemEvent, priority: EventPriority) {}
     fun onCompostByEntity(event: EntityCompostItemEvent, priority: EventPriority) {}
 
+    @ApiStatus.Internal
     companion object : MultiListener {
         @UniversalHandler
         private fun onCompostByHopper(event: CompostItemEvent, priority: EventPriority) {