Merge pull request #31 from CodeMonkeysMods/coderabbitai/docstrings/4d00701

📝 Add docstrings to `feat/add-workbench`

Author: The-Code-Monkey

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

@@ -24,9 +24,9 @@ public class WorkbenchWorkbenchScreen extends AbstractRecipeBookScreen<Workbench
         Identifier.fromNamespaceAndPath(MineTale.MOD_ID, "textures/gui/container/furnace_workbench.png");
 
     /**
-     * Creates a campfire workbench screen for the provided menu, player inventory, and title.
+     * Initialize a workbench GUI screen using the provided container menu, player inventory, and title.
      *
-     * @param menu      the container menu that provides slots and synchronizes state for this screen
+     * @param menu      the menu supplying slots and synchronized 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,8 +35,10 @@ public WorkbenchWorkbenchScreen(WorkbenchWorkbenchMenu menu, Inventory inventory
     }
 
     /**
-     * Static helper to build the component with the custom MineTale tabs 
-     * before the super constructor is called.
+     * Create a MineTaleRecipeBookComponent configured for the workbench screen.
+     *
+     * @param menu the workbench menu used to initialize the recipe book component
+     * @return a MineTaleRecipeBookComponent containing the workbench tab and associated recipe category
      */
     private static MineTaleRecipeBookComponent createRecipeBookComponent(WorkbenchWorkbenchMenu menu) {
         ItemStack tabIcon = new ItemStack(ModBlocks.WORKBENCH_WORKBENCH_BLOCK.asItem());
@@ -49,7 +51,10 @@ private static MineTaleRecipeBookComponent createRecipeBookComponent(WorkbenchWo
     }
 
     /**
-     * Initializes the screen and centers the title horizontally by setting {@code titleLabelX}.
+     * Sets the screen's GUI size and initializes layout so the title is centered.
+     *
+     * Sets imageWidth to 176 and imageHeight to 166 before delegating to the superclass
+     * init method to complete widget and layout initialization (including horizontal title centering).
      */
     @Override
     protected void init() {
@@ -61,12 +66,12 @@ protected void init() {
     }
 
     /**
-    * Renders the campfire workbench background texture at the screen's top-left position.
+    * Renders the workbench GUI background texture at the screen's top-left position.
     *
-    * @param guiGraphics the graphics context used for drawing
-    * @param f           partial ticks for interpolation
-    * @param i           current mouse x position
-    * @param j           current mouse y position
+    * @param guiGraphics the graphics context for drawing
+    * @param f           partial tick time used for interpolation
+    * @param i           current mouse x coordinate
+    * @param j           current mouse y coordinate
     */
    protected void renderBg(GuiGraphics guiGraphics, float f, int i, int j) {
       int k = this.leftPos;
@@ -75,13 +80,13 @@ protected void renderBg(GuiGraphics guiGraphics, float f, int i, int j) {
    }
 
     /**
-         * 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
-         */
+     * Renders the workbench screen including the background tint, GUI elements, and tooltips.
+     *
+     * @param graphics the graphics context
+     * @param mouseX the current mouse x-coordinate
+     * @param mouseY the current mouse y-coordinate
+     * @param delta the partial tick delta for frame interpolation
+     */
     @Override
     public void render(GuiGraphics graphics, int mouseX, int mouseY, float delta) {
         // 1. Always render the dark background tint first
@@ -93,6 +98,11 @@ public void render(GuiGraphics graphics, int mouseX, int mouseY, float delta) {
         renderTooltip(graphics, mouseX, mouseY);
     }
 
+    /**
+     * Compute the on-screen position for the recipe book toggle button for this GUI.
+     *
+     * @return the ScreenPosition located 5 pixels from the GUI's left edge and 49 pixels above the GUI's vertical center
+     */
     @Override
     protected ScreenPosition getRecipeBookButtonPosition() {
         // 1. Calculate the start (left) of your workbench GUI

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

@@ -30,9 +30,9 @@ public class WorkbenchWorkbench extends AbstractWorkbench<WorkbenchWorkbenchEnti
     public static final MapCodec<WorkbenchWorkbench> CODEC = simpleCodec(WorkbenchWorkbench::new);
 
     /**
-     * Creates a WorkbenchWorkbench configured to use the mod's WORKBENCH_WORKBENCH_BE block entity type.
+     * Constructs a WorkbenchWorkbench that uses the mod's WORKBENCH_WORKBENCH_BE block entity type.
      *
-     * @param properties block properties used to construct this workbench
+     * @param properties block properties for this workbench
      */
     public WorkbenchWorkbench(Properties properties) {
         // Hardcode the supplier and sounds here if they never change
@@ -51,9 +51,9 @@ public WorkbenchWorkbench(Properties properties, Supplier<BlockEntityType<? exte
     }
 
     /**
-     * Provides a ticker that updates workbench workbench block entities each tick.
+     * Supplies a ticker that updates WorkbenchWorkbench block entities each tick.
      *
-     * @return a BlockEntityTicker that invokes AbstractWorkbenchEntity.tick for WorkbenchWorkbenchEntity instances, or `null` if the supplied block entity type does not match the workbench workbench type.
+     * @return a BlockEntityTicker that invokes AbstractWorkbenchEntity.tick for matching WorkbenchWorkbenchEntity instances, `null` if the supplied block entity type does not match
      */
     @Nullable
     @Override
@@ -63,7 +63,7 @@ public <T extends BlockEntity> BlockEntityTicker<T> getTicker(Level level, Block
     }
 
     /**
-     * The codec used to serialize and deserialize this WorkbenchWorkbench type.
+     * Provides the MapCodec used to serialize and deserialize this workbench.
      *
      * @return the MapCodec for this WorkbenchWorkbench
      */
@@ -87,9 +87,11 @@ public RenderShape getRenderShape(BlockState state) {
     private static final VoxelShape SHAPE = Block.box(0, 0, 0, 16, 7, 16);
 
     /**
-     * Gets the block's collision and interaction shape.
+     * Provides the block's collision and interaction shape.
      *
-     * @return the voxel shape representing the block's collision and interaction bounds
+     * <p>Uses a fixed voxel shape covering a 1×1 footprint with a height of 7 units (coordinates: x 0–16, y 0–7, z 0–16).</p>
+     *
+     * @return the voxel shape used for collision and interaction
      */
     @Override
     public VoxelShape getShape(BlockState state, BlockGetter level, BlockPos pos, CollisionContext context) {

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

@@ -50,12 +50,12 @@ public int get(int index) {
         }
 
         /**
-         * Sets an internal workbench data field identified by index.
+         * Update an internal workbench data field identified by index.
          *
          * Supported indices:
          * <ul>
-         *   <li>0 — sets {@code fuelTime}</li>
-         *   <li>2 — sets {@code cookTime}</li>
+         *   <li>0 — set {@code fuelTime}</li>
+         *   <li>2 — set {@code cookTime}</li>
          * </ul>
          * Other indices are ignored.
          *
@@ -97,10 +97,14 @@ public WorkbenchWorkbenchEntity(BlockPos blockPos, BlockState blockState) {
     }
 
     /**
-     * Performs server-side per-tick updates for this workbench.
+     * Run server-side per-tick updates for this workbench entity.
      *
-     * <p>This method is a no-op on the client and exits immediately; server-side update logic
-     * should be implemented here.
+     * <p>Does nothing on the client. On the server this advances the input queue so the next
+     * item becomes ready and, if any state changes occur, marks the block entity as changed.
+     *
+     * @param level the world in which the workbench exists
+     * @param pos the position of the workbench block
+     * @param state the current block state at the workbench's position
      */
     public void tick(Level level, BlockPos pos, BlockState state) {
         if (level.isClientSide()) return;
@@ -118,8 +122,9 @@ public void tick(Level level, BlockPos pos, BlockState state) {
     }
 
     /**
-     * Iterates through the queue range. If a slot is empty, it pulls the item 
-     * from the slot behind it.
+     * Compacts the input queue by moving items forward into the first empty slot ahead of them.
+     *
+     * @return `true` if any items were moved, `false` otherwise.
      */
     private boolean shiftQueueForward() {
         boolean moved = false;
@@ -152,12 +157,12 @@ private boolean shiftQueueForward() {
     // private boolean isFuel(ItemStack stack) { return stack.is(ItemTags.LOGS_THAT_BURN) || stack.is(Items.STICK); }
 
     /**
-     * Persist entity-specific state into the provided ValueOutput.
+     * Persist this workbench's state to the given ValueOutput.
      *
-     * Stores the workbench's tier as "WorkbenchTier" and its scan radius as "ScanRadius"
+     * Stores "WorkbenchTier" (int), "ScanRadius" (double), and the full inventory under "Inventory"
      * using type-safe Codecs.
      *
-     * @param valueOutput the output writer used to serialize this entity's fields
+     * @param valueOutput the writer used to serialize this entity's fields
      */
     @Override
     protected void saveAdditional(ValueOutput valueOutput) {
@@ -201,22 +206,22 @@ protected void loadAdditional(ValueInput valueInput) {
     }
 
     /**
-     * Create the server-side container menu for the workbench workbench UI.
+     * Creates the server-side container menu for this workbench's UI.
      *
-     * @param syncId         window id used to synchronize the menu with the client
+     * @param syncId the 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 WorkbenchWorkbenchMenu tied to this workbench's inventory and sync data
+     * @param player the player who opened the menu
+     * @return a WorkbenchWorkbenchMenu bound to this workbench's inventory and synced data
      */
     @Override
     public @Nullable AbstractContainerMenu createMenu(int syncId, Inventory playerInventory, Player player) {
         return new WorkbenchWorkbenchMenu(syncId, playerInventory, this.inventory, this.data, this);
     }
 
     /**
-     * Specifies which recipe type this workbench uses.
+     * Identifies the recipe type used to find and match recipes for this workbench.
      *
-     * @return the workbench workbench recipe type used to look up and match recipes
+     * @return the RecipeType for workbench recipes
      */
     @Override
     public RecipeType<WorkbenchRecipe> getWorkbenchRecipeType() {

src/main/java/com/tcm/MineTale/block/workbenches/menu/WorkbenchWorkbenchMenu.java

@@ -23,10 +23,10 @@ public class WorkbenchWorkbenchMenu extends AbstractWorkbenchContainerMenu {
     private final AbstractWorkbenchEntity blockEntity;
 
     /**
-     * Creates a WorkbenchWorkbenchMenu using default internal storage and data containers.
+     * Constructs a WorkbenchWorkbenchMenu backed by default internal storage and data.
      *
-     * Constructs a menu with a new SimpleContainer of size {@code containerSize} and a new
-     * SimpleContainerData of size {@code containerDataSize}, then delegates to the primary constructor.
+     * Initializes the menu with a new 7-slot SimpleContainer and a SimpleContainerData of size
+     * {@code containerDataSize}, and binds it to the provided player inventory.
      *
      * @param syncId          synchronization id for the menu
      * @param playerInventory the player's inventory interacting with this menu
@@ -36,23 +36,34 @@ public WorkbenchWorkbenchMenu(int syncId, Inventory playerInventory) {
     }
 
     /**
-     * Creates a WorkbenchWorkbenchMenu bound to the given player inventory, container, and container data.
+     * Creates a workbench menu bound to the given player inventory, container, container data, and optional block entity.
      *
-     * @param syncId the synchronization id for this menu (used by the client/server container sync)
+     * @param syncId synchronization id for this menu
      * @param playerInventory the player's inventory
-     * @param container the backing container for the workbench slots
-     * @param data the container data used for syncing additional numeric state
+     * @param container backing container for the workbench slots
+     * @param data container data used to sync numeric state
+     * @param blockEntity optional block entity this menu is bound to, or `null` if not bound
      */
     public WorkbenchWorkbenchMenu(int syncId, Inventory playerInventory, Container container, ContainerData data, @Nullable AbstractWorkbenchEntity blockEntity) {
         super(ModMenuTypes.WORKBENCH_WORKBENCH_MENU, syncId, container, data, containerDataSize, playerInventory, Constants.INPUT_START + 1, 6);
         this.blockEntity = blockEntity;
     }
 
+    /**
+     * Accesses the block entity bound to this menu, if present.
+     *
+     * @return the bound AbstractWorkbenchEntity, or {@code null} if this menu is not bound to a block entity
+     */
     @Override
     public @Nullable AbstractWorkbenchEntity getBlockEntity() {
         return this.blockEntity;
     }
 
+    /**
+     * Populate the provided StackedItemContents with the items currently present in this menu's crafting slots so the recipe book can evaluate available recipes.
+     *
+     * @param stackedItemContents container to be filled with consolidated item counts from the menu's crafting/container slots
+     */
     @Override
     public void fillCraftSlotsStackedContents(StackedItemContents stackedItemContents) {
         // This is vital for the recipe book to "see" what is currently in your furnace.
@@ -62,11 +73,23 @@ public void fillCraftSlotsStackedContents(StackedItemContents stackedItemContent
         }
     }
 
+    /**
+     * Identifies the recipe book category used by this menu.
+     *
+     * @return the crafting recipe book type, `RecipeBookType.CRAFTING`.
+     */
     @Override
     public RecipeBookType getRecipeBookType() {
         return RecipeBookType.CRAFTING;
     }
 
+    /**
+     * Creates a WorkbenchRecipeInput using the current items in the menu's left and right input slots.
+     *
+     * The left input is read from index {@code Constants.INPUT_START} and the right input from {@code inputEnd}.
+     *
+     * @return a WorkbenchRecipeInput containing the items currently in the left and right input slots
+     */
     @Override
     public WorkbenchRecipeInput createRecipeInput() {
         // We grab the items currently sitting in the container at indices 0 and 1

src/main/java/com/tcm/MineTale/registry/ModBlockEntities.java

@@ -26,7 +26,14 @@ public class ModBlockEntities {
         ModBlocks.WORKBENCH_WORKBENCH_BLOCK
     );
 
-    // Helper method to register AND add to map simultaneously
+    /**
+     * Register a BlockEntityType for the given furnace tier and store it in the tier map.
+     *
+     * @param tier  the furnace tier whose BlockEntityType will be registered
+     * @param block the block to associate with the registered BlockEntityType; must not be null
+     * @return      the registered BlockEntityType for the specified furnace tier
+     * @throws IllegalStateException if {@code block} is null
+     */
     private static BlockEntityType<FurnaceWorkbenchEntity> registerTier(ModTiers.FurnaceTier tier, Block block) {
         // If 'block' is null here, the game WILL crash later. 
         // We can check it now to prove the theory:

src/main/java/com/tcm/MineTale/registry/ModBlocks.java

@@ -90,9 +90,9 @@ public class ModBlocks {
 	public static final Block WILD_WISTERIA_WOOD = register("wild_wisteria_wood", RotatedPillarBlock::new, BlockBehaviour.Properties.of().mapColor(MapColor.DIRT).instrument(NoteBlockInstrument.BASS).strength(2.0F).sound(SoundType.WOOD).ignitedByLava(), true);
 
     /**
-     * Registers this mod's blocks into the Functional Blocks creative tab and records the registration.
+     * Registers the mod's workbench and furnace blocks into the Functional Blocks creative tab and logs the registration.
      *
-     * Adds CAMPFIRE_WORKBENCH_BLOCK and FURNACE_WORKBENCH_BLOCK to CreativeModeTabs.FUNCTIONAL_BLOCKS and prints a registration message including the mod ID.
+     * Specifically registers CAMPFIRE_WORKBENCH_BLOCK, WORKBENCH_WORKBENCH_BLOCK, FURNACE_WORKBENCH_BLOCK_T1, and FURNACE_WORKBENCH_BLOCK_T2, then prints a message containing the mod ID.
      */
     public static void initialize() { 
 		ItemGroupEvents.modifyEntriesEvent(CreativeModeTabs.FUNCTIONAL_BLOCKS).register(entries -> {

src/main/java/com/tcm/MineTale/registry/ModRecipeDisplay.java

@@ -33,6 +33,11 @@ public class ModRecipeDisplay {
 
     public static final RecipeBookCategory FURNACE_T1_SEARCH = registerCategory("furnace_t1_recipe_book_category");
 
+    /**
+     * Registers the workbench recipe display type into the built-in recipe display registry.
+     *
+     * The registration uses this mod's ID combined with the path "workbench_recipe_display" as the identifier.
+     */
     public static void initialize() {
         // Register the Display TYPE
         Registry.register(
@@ -49,4 +54,4 @@ private static RecipeBookCategory registerCategory(String name) {
         // Register it in the game's internal registry
         return Registry.register(BuiltInRegistries.RECIPE_BOOK_CATEGORY, id, category);
     }
-}
+}

src/main/java/com/tcm/MineTale/registry/ModRecipes.java

@@ -28,6 +28,12 @@ public class ModRecipes {
     public static final RecipeSerializer<WorkbenchRecipe> WORKBENCH_SERIALIZER =
         new WorkbenchRecipe.Serializer(WORKBENCH_TYPE);
 
+    /**
+     * Registers the mod's recipe types and their serializers into the game's built-in registries.
+     *
+     * Specifically registers the furnace (FURNACE_T1_TYPE), campfire (CAMPFIRE_TYPE),
+     * and workbench (WORKBENCH_TYPE) recipe types with their corresponding serializers.
+     */
     public static void initialize() {
         // Register the Furnace-flavored version
         register(FURNACE_T1_TYPE.toString(), FURNACE_T1_TYPE, FURNACE_SERIALIZER);