Merge pull request #19 from CodeMonkeysMods/coderabbitai/docstrings/d0b26c3

📝 Add docstrings to `feat/add-furnace-block-basics`

Author: The-Code-Monkey

src/client/java/com/tcm/MineTale/MineTaleClient.java

@@ -8,6 +8,12 @@
 import net.minecraft.client.gui.screens.MenuScreens;
 
 public class MineTaleClient implements ClientModInitializer {
+	/**
+	 * Registers client-side screen factories for custom workbench menu types.
+	 *
+	 * Binds the furnace and campfire workbench menu types to their corresponding screen constructors
+	 * so the client can create the appropriate GUI when those menus are opened.
+	 */
 	@Override
 	public void onInitializeClient() {
 		MenuScreens.register(ModMenuTypes.FURNACE_WORKBENCH_MENU, FurnaceWorkbenchScreen::new);

src/client/java/com/tcm/MineTale/block/workbenches/screen/CampfireWorkbenchScreen.java

@@ -15,9 +15,9 @@ public class CampfireWorkbenchScreen extends AbstractContainerScreen<CampfireWor
         Identifier.withDefaultNamespace("textures/gui/container/furnace.png");
 
     /**
-     * Creates a new furnace workbench screen for the given menu, player inventory, and title.
+     * Creates a campfire workbench screen for the provided menu, player inventory, and title.
      *
-     * @param menu      the container menu that provides slots and syncs state for this screen
+     * @param menu      the container menu that provides slots and synchronizes state for this screen
      * @param inventory the player's inventory to display and interact with
      * @param title     the title component shown at the top of the screen
      */
@@ -35,10 +35,10 @@ protected void init() {
     }
 
     /**
-    * Draws the furnace workbench background texture onto the screen.
+    * Renders the campfire workbench background texture at the screen's top-left position.
     *
     * @param guiGraphics the graphics context used for drawing
-    * @param f           partial tick time used for interpolation
+    * @param f           partial ticks for interpolation
     * @param i           current mouse x position
     * @param j           current mouse y position
     */
@@ -49,13 +49,13 @@ protected void renderBg(GuiGraphics guiGraphics, float f, int i, int j) {
    }
 
     /**
-     * Renders the furnace workbench screen, drawing its background, contents, and tooltips.
-     *
-     * @param graphics the graphics context used for rendering
-     * @param mouseX   the current mouse X coordinate
-     * @param mouseY   the current mouse Y coordinate
-     * @param delta    the frame time delta (partial tick) used for animated rendering
-     */
+         * Renders the campfire workbench screen, drawing its background, contents, and tooltips.
+         *
+         * @param graphics the graphics context used for rendering
+         * @param mouseX   the current mouse X coordinate
+         * @param mouseY   the current mouse Y coordinate
+         * @param delta    the frame time delta (partial tick) used for animated rendering
+         */
     @Override
     public void render(GuiGraphics graphics, int mouseX, int mouseY, float delta) {
         renderBackground(graphics, mouseX, mouseY, delta);

src/main/java/com/tcm/MineTale/block/workbenches/CampfireWorkbench.java

@@ -43,24 +43,33 @@ public CampfireWorkbench(Properties properties) {
     }
 
     /**
-     * Creates a CampfireWorkbench with the given block properties and block-entity type supplier.
+     * Constructs a CampfireWorkbench using the provided block properties and block-entity type supplier.
      *
-     * @param properties the block's properties
-     * @param supplier   supplier that provides the BlockEntityType for this workbench
+     * @param properties block properties to apply to this workbench
+     * @param supplier   supplier that provides the BlockEntityType for the CampfireWorkbenchEntity
      */
     public CampfireWorkbench(Properties properties, Supplier<BlockEntityType<? extends CampfireWorkbenchEntity>> supplier) {
         // isWide = false, isTall = false (1x1 footprint)
         super(properties, supplier, IS_WIDE, IS_TALL);
     }
 
-    // In your CampfireWorkbenchBlock.java (The Block class)
+    /**
+     * Provides a ticker that updates campfire workbench block entities each tick.
+     *
+     * @return a BlockEntityTicker that invokes AbstractWorkbenchEntity.tick for CampfireWorkbenchEntity instances, or `null` if the supplied block entity type does not match the campfire workbench type.
+     */
     @Nullable
     @Override
     public <T extends BlockEntity> BlockEntityTicker<T> getTicker(Level level, BlockState state, BlockEntityType<T> type) {
         // This connects the Level's ticking system to your static tick method
         return createTickerHelper(type, ModBlockEntities.CAMPFIRE_WORKBENCH_BE, AbstractWorkbenchEntity::tick);
     }
 
+    /**
+     * The codec used to serialize and deserialize this CampfireWorkbench type.
+     *
+     * @return the MapCodec for this CampfireWorkbench
+     */
     @Override
     protected MapCodec<? extends CampfireWorkbench> codec() {
         return CODEC;
@@ -91,9 +100,11 @@ public VoxelShape getShape(BlockState state, BlockGetter level, BlockPos pos, Co
     }
 
     /**
-     * Create the block entity for this block; only the master block of the multi-block workbench receives an entity.
+     * Create a block entity for the master block of this workbench.
+     *
+     * Only the master block of the multi-block workbench receives an entity; other positions return {@code null}.
      *
-     * @return the created {@link BlockEntity} for the master block, or `null` if this position does not host an entity
+     * @return the block entity for the master block ({@link CampfireWorkbenchEntity}), or {@code null} if this position does not host an entity
      */
     @Nullable
     @Override

src/main/java/com/tcm/MineTale/block/workbenches/entity/AbstractWorkbenchEntity.java

@@ -47,11 +47,28 @@ public AbstractWorkbenchEntity(BlockEntityType<?> type, BlockPos pos, BlockState
     }
 
     /**
-     * Subclasses (Campfire/Furnace) must define which recipe type they look for.
-     */
+ * Specifies the RecipeType used by this workbench to look up WorkbenchRecipe instances.
+ *
+ * Implementations must return the RecipeType corresponding to the recipe family this workbench processes (for example, campfire- or furnace-style recipes).
+ *
+ * @return the RecipeType for this workbench's WorkbenchRecipe
+ */
     public abstract RecipeType<WorkbenchRecipe> getWorkbenchRecipeType();
 
-    public static void tick(Level level, BlockPos pos, BlockState state, AbstractWorkbenchEntity entity) {
+    /**
+ * Performs a single server-side tick for the given workbench entity: looks up a matching WorkbenchRecipe
+ * for the entity's input slots and, if possible, advances crafting progress, consumes fuel/inputs,
+ * inserts results into output slots, and updates block-entity state.
+ *
+ * This method will set or reset the entity's progress and maxProgress according to the found recipe,
+ * invoke craft(...) when progress completes, and call setChanged(...) to mark the block entity as modified.
+ *
+ * @param level  the world where the workbench resides; must provide a server RecipeManager for recipe lookup
+ * @param pos    the block position of the workbench
+ * @param state  the current block state at the workbench position
+ * @param entity the workbench block entity to tick; this object is mutated (progress, maxProgress, inventory)
+ */
+public static void tick(Level level, BlockPos pos, BlockState state, AbstractWorkbenchEntity entity) {
     // 1. Create the input wrapper using the internal SimpleContainer
     // Slot 1 = Input A, Slot 2 = Input B
     WorkbenchRecipeInput input = new WorkbenchRecipeInput(
@@ -125,8 +142,20 @@ public static void tick(Level level, BlockPos pos, BlockState state, AbstractWor
     }
 }
 
-    public ItemStack getItem(int slot) { return this.inventory.getItem(slot); }
+    /**
+ * Retrieve the ItemStack stored in the given inventory slot.
+ *
+ * @param slot the index of the inventory slot to read
+ * @return the ItemStack in the specified slot; may be an empty stack if the slot is empty
+ */
+public ItemStack getItem(int slot) { return this.inventory.getItem(slot); }
 
+    /**
+     * Checks whether all result ItemStacks can be placed into the workbench's output slot range.
+     *
+     * @param results the list of result ItemStacks to validate
+     * @return `true` if every stack in `results` has an available output slot (empty or able to accept the stack), `false` otherwise
+     */
     public boolean canFitOutputs(List<ItemStack> results) {
         for (ItemStack result : results) {
             // If we can't find a home for even one of the results, return false
@@ -137,6 +166,17 @@ public boolean canFitOutputs(List<ItemStack> results) {
         return true;
     }
 
+    /**
+     * Finds a suitable output slot between the given indices (inclusive) for placing the specified result stack.
+     *
+     * The method returns the first index that is either empty or already contains the same item with the same
+     * components and has enough space to accommodate the result's count.
+     *
+     * @param result the stack to place into an output slot
+     * @param start  the starting slot index (inclusive)
+     * @param end    the ending slot index (inclusive)
+     * @return the index of a suitable slot, or -1 if no such slot exists
+     */
     public int findOutputSlot(ItemStack result, int start, int end) {
         for (int i = start; i <= end; i++) {
             ItemStack stack = getItem(i);
@@ -151,14 +191,33 @@ public int findOutputSlot(ItemStack result, int start, int end) {
         return -1;
     }
 
+    /**
+     * Get the number of slots in this entity's internal inventory.
+     *
+     * @return the number of slots in the internal inventory
+     */
     public int getContainerSize() {
         return this.inventory.getContainerSize();
     }
 
+    /**
+     * Check whether the workbench's internal inventory contains no items.
+     *
+     * @return `true` if the internal inventory contains no items, `false` otherwise.
+     */
     public boolean isEmpty() {
         return this.inventory.isEmpty();
     }
 
+    /**
+     * Consume one item from each input slot and insert the recipe's results into the workbench output slots.
+     *
+     * Each non-empty result is placed into the first suitable output slot in the configured output range:
+     * if the slot is empty the result is copied into it; if the slot contains the same item the stack is increased.
+     * Results that cannot be placed (no suitable output slot) are skipped.
+     *
+     * @param recipe the WorkbenchRecipe whose results will be produced and placed into outputs
+     */
     protected void craft(WorkbenchRecipe recipe) {
         // 1. Consume 1 from each ingredient slot (Slots 1 and 2)
         this.removeItem(Constants.INPUT_1, 1);
@@ -184,6 +243,13 @@ protected void craft(WorkbenchRecipe recipe) {
         }
     }
 
+    /**
+     * Remove up to the specified number of items from the given inventory slot.
+     *
+     * @param slot   the index of the slot to remove items from
+     * @param amount the maximum number of items to remove
+     * @return the ItemStack removed from the slot, or an empty stack if nothing was removed
+     */
     public ItemStack removeItem(int slot, int amount) {
         // SimpleContainer has its own removeItem logic built-in
         ItemStack result = this.inventory.removeItem(slot, amount);
@@ -193,6 +259,12 @@ public ItemStack removeItem(int slot, int amount) {
         return result;
     }
 
+    /**
+     * Places the given ItemStack into the specified inventory slot, clamps its count to the stack limit, and marks the block entity as changed.
+     *
+     * @param slot  the index of the inventory slot to set
+     * @param stack the ItemStack to put into the slot; if its count exceeds the item's max stack size it will be reduced to that maximum
+     */
     public void setItem(int slot, ItemStack stack) {
         // Use setItem(), not set()
         this.inventory.setItem(slot, stack);
@@ -204,7 +276,11 @@ public void setItem(int slot, ItemStack stack) {
         this.setChanged();
     }
 
-    // Subclasses handle fuel logic (Campfires might return true always, Furnaces check slot 2)
+    /**
+ * Indicates whether this workbench currently has fuel available to perform crafting.
+ *
+ * @return `true` if the workbench has fuel available, `false` otherwise.
+ */
     protected abstract boolean hasFuel();
 
     /**
@@ -254,10 +330,13 @@ public List<Container> getNearbyInventories() {
     }
 
     /**
-     * Finds the first output slot that can accept the given result.
+     * Locate the first slot in the given inventory range that can accept the provided result stack.
      *
-     * @param result the item stack to place into an output slot
-     * @return the index of the first suitable output slot between OUTPUT_START and OUTPUT_END, or -1 if none is available
+     * @param result    the stack to place into an output slot
+     * @param inventory the container to search
+     * @param start     inclusive start index of the search range
+     * @param end       inclusive end index of the search range
+     * @return the index of a slot that is empty or contains the same item with enough space for the result, or -1 if none found
      */
     public int findOutputSlot(ItemStack result, SimpleContainer inventory, int start, int end) {
         for (int i = start; i <= end; i++) {

src/main/java/com/tcm/MineTale/block/workbenches/entity/CampfireWorkbenchEntity.java

@@ -81,9 +81,9 @@ public int getCount() {
     };
 
     /**
-     * Creates a CampfireWorkbenchEntity at the given position with the provided block state.
+     * Creates a CampfireWorkbenchEntity for the specified world position and block state.
      *
-     * Initializes the entity's scan radius to 6.0 and tier to 1.
+     * Sets the entity's scanRadius to 0.0 and tier to 1.
      *
      * @param blockPos   the world position of this block entity
      * @param blockState the block state for this block entity
@@ -95,6 +95,12 @@ public CampfireWorkbenchEntity(BlockPos blockPos, BlockState blockState) {
         this.tier = 1;
     }
 
+    /**
+     * Performs server-side per-tick updates for this workbench.
+     *
+     * <p>This method is a no-op on the client and exits immediately; server-side update logic
+     * should be implemented here.
+     */
     public void tick(Level level, BlockPos pos, BlockState state) {
         if (level.isClientSide()) return;
     }
@@ -140,11 +146,12 @@ protected void saveAdditional(ValueOutput valueOutput) {
     }
 
     /**
-     * Restores workbench-specific state from persistent storage and applies defaults when keys are absent.
+     * Restores workbench-specific state from persistent storage, applying defaults when keys are absent.
      *
-     * Delegates to the superclass load logic, then reads:
-     * - "WorkbenchTier" (int) into {@code tier}, defaulting to {@code 1} if missing.
-     * - "ScanRadius" (double) into {@code scanRadius}, defaulting to {@code 5.0} if missing.
+     * Delegates to the superclass load logic, then:
+     * - reads "WorkbenchTier" (int) into {@code tier}, defaulting to {@code 1} if missing;
+     * - reads "ScanRadius" (double) into {@code scanRadius}, defaulting to {@code 0.0} if missing;
+     * - reads "Inventory" as a list of {@code ItemStack} and populates the internal inventory up to its capacity.
      */
     @Override
     protected void loadAdditional(ValueInput valueInput) {
@@ -161,16 +168,36 @@ protected void loadAdditional(ValueInput valueInput) {
         });
     }
 
+    /**
+     * Create the server-side container menu for the campfire workbench UI.
+     *
+     * @param syncId         window id used to synchronize the menu with the client
+     * @param playerInventory the opening player's inventory
+     * @param player         the player who opened the menu
+     * @return               a CampfireWorkbenchMenu tied to this workbench's inventory and sync data
+     */
     @Override
     public @Nullable AbstractContainerMenu createMenu(int syncId, Inventory playerInventory, Player player) {
         return new CampfireWorkbenchMenu(syncId, playerInventory, this.inventory, this.data);
     }
 
+    /**
+     * Specifies which recipe type this workbench uses.
+     *
+     * @return the campfire workbench recipe type used to look up and match recipes
+     */
     @Override
     public RecipeType<WorkbenchRecipe> getWorkbenchRecipeType() {
         return ModRecipes.CAMPFIRE_TYPE;
     }
 
+    /**
+     * Determines whether the workbench currently has fuel available.
+     *
+     * Checks that the entity is in a loaded level and that the configured fuel slot contains an item.
+     *
+     * @return `true` if the entity is in a loaded level and the fuel slot contains an item, `false` otherwise.
+     */
     @Override
     protected boolean hasFuel() {
         if (this.level == null) return false;