Adding Javadocs to CounterCommand.java and relevant files (#838)

* adding class javadoc

Co-authored-by: gnembon <41132274+gnembon@users.noreply.github.com>

src/main/java/carpet/commands/CounterCommand.java

@@ -11,8 +11,15 @@ import net.minecraft.server.command.CommandManager;
 import net.minecraft.util.DyeColor;
 import net.minecraft.text.BaseText;
 
+/**
+ * Class for the /counter command which allows to use hoppers pointing into wool
+ */
+
 public class CounterCommand
 {
+    /**
+     * The method used to register the command and make it available for the players to use.
+     */
     public static void register(CommandDispatcher<ServerCommandSource> dispatcher)
     {
         LiteralArgumentBuilder<ServerCommandSource> literalargumentbuilder = CommandManager.literal("counter").executes((context)
@@ -37,6 +44,13 @@ public class CounterCommand
         dispatcher.register(literalargumentbuilder);
     }
 
+    /**
+     * A method to prettily display the contents of a counter to the player
+     * @param color The counter colour whose contents we are querying.
+     * @param realtime Whether or not to display it as in-game time or IRL time, which accounts for less than 20TPS which
+     *                would make it slower than IRL
+     */
+
     private static int displayCounter(ServerCommandSource source, String color, boolean realtime)
     {
         HopperCounter counter = HopperCounter.getCounter(color);
@@ -49,6 +63,11 @@ public class CounterCommand
         return 1;
     }
 
+    /**
+     * A method to reset the counter's timer to 0 and empty its items. If the {@code color} parameter is {@code null},
+     * it will reset all counters.
+     * @param color The counter whose contents we want to reset
+     */
     private static int resetCounter(ServerCommandSource source, String color)
     {
         if (color == null)
@@ -66,6 +85,11 @@ public class CounterCommand
         return 1;
     }
 
+    /**
+     * A method to prettily display all the counters to the player
+     * @param realtime Whether or not to display it as in-game time or IRL time, which accounts for less than 20TPS which
+     *                would make it slower than IRL
+     */
     private static int listAllCounters(ServerCommandSource source, boolean realtime)
     {
         for (BaseText message: HopperCounter.formatAll(source.getMinecraftServer(), realtime))

src/main/java/carpet/fakes/IngredientInterface.java

@@ -7,5 +7,9 @@ import java.util.List;
 
 public interface IngredientInterface
 {
+    /**
+     * Gets all the stacks of the ingredients for a given item recipe. Also used for {@link carpet.helpers.HopperCounter#guessColor}
+     * to guess the colour of an item to display it prettily
+     */
     List<Collection<ItemStack>> getRecipeStacks();
 }

src/main/java/carpet/fakes/RecipeManagerInterface.java

@@ -1,5 +1,6 @@
 package carpet.fakes;
 
+import net.minecraft.item.Item;
 import net.minecraft.recipe.Recipe;
 import net.minecraft.recipe.RecipeType;
 import net.minecraft.util.Identifier;
@@ -8,5 +9,9 @@ import java.util.List;
 
 public interface RecipeManagerInterface
 {
+    /**
+     * Gets all the recipes for a given item. Also used for {@link carpet.helpers.HopperCounter#guessColor} to guess the
+     * colour of an item to display it prettily
+     */
     List<Recipe<?>> getAllMatching(RecipeType type, Identifier output);
 }

src/main/java/carpet/helpers/HopperCounter.java

@@ -42,9 +42,22 @@ import java.util.Locale;
 import java.util.Map;
 import java.util.stream.Collectors;
 
+/**
+ * The actual object residing in each hopper counter which makes them count the items and saves them. There is one for each
+ * colour in MC.
+ */
+
 public class HopperCounter
 {
+    /**
+     * A map of all the {@link HopperCounter} counters.
+     */
     public static final Map<DyeColor, HopperCounter> COUNTERS;
+
+    /**
+     * The default display colour of each item, which makes them look nicer when printing the counter contents to the chat
+     */
+
     public static final TextColor WHITE = TextColor.fromFormatting(Formatting.WHITE);
 
     static
@@ -57,10 +70,29 @@ public class HopperCounter
         COUNTERS = Maps.immutableEnumMap(counterMap);
     }
 
+    /**
+     * The counter's colour, determined by the colour of wool it's pointing into
+     */
     public final DyeColor color;
+    /**
+     * The string which is passed into {@link Messenger#m} which makes each counter name be displayed in the colour of
+     * that counter.
+     */
     private final String prettyColour;
+    /**
+     * All the items stored within the counter, as a map of {@link Item} mapped to a {@code long} of the amount of items
+     * stored thus far of that item type.
+     */
     private final Object2LongMap<Item> counter = new Object2LongLinkedOpenHashMap<>();
+    /**
+     * The starting tick of the counter, used to calculate in-game time. Only initialised when the first item enters the
+     * counter
+     */
     private long startTick;
+    /**
+     * The starting millisecond of the counter, used to calculate IRl time. Only initialised when the first item enters
+     * the counter
+     */
     private long startMillis;
     // private PubSubInfoProvider<Long> pubSubProvider;
 
@@ -71,6 +103,11 @@ public class HopperCounter
         this.prettyColour = WoolTool.Material2DyeName.getOrDefault(color.getMaterialColor(),"w ") + color.getName();
     }
 
+    /**
+     * Method used to add items to the counter. Note that this is when the {@link HopperCounter#startTick} and
+     * {@link HopperCounter#startMillis} variables are initialised, so you can place the counters and then start the farm
+     * after all the collection is sorted out.
+     */
     public void add(MinecraftServer server, ItemStack stack)
     {
         if (startTick < 0)
@@ -83,6 +120,9 @@ public class HopperCounter
         // pubSubProvider.publish();
     }
 
+    /**
+     * Resets the counter, clearing its items but keeping the clock running.
+     */
     public void reset(MinecraftServer server)
     {
         counter.clear();
@@ -91,6 +131,10 @@ public class HopperCounter
         // pubSubProvider.publish();
     }
 
+    /**
+     * Resets all counters, clearing their items.
+     * @param fresh Whether or not to start the clocks going immediately or later.
+     */
     public static void resetAll(MinecraftServer server, boolean fresh)
     {
         for (HopperCounter counter : COUNTERS.values())
@@ -100,6 +144,9 @@ public class HopperCounter
         }
     }
 
+    /**
+     * Prints all the counters to chat, nicely formatted, and you can choose whether to diplay in in game time or IRL time
+     */
     public static List<BaseText> formatAll(MinecraftServer server, boolean realtime)
     {
         List<BaseText> text = new ArrayList<>();
@@ -120,6 +167,10 @@ public class HopperCounter
         return text;
     }
 
+    /**
+     * Prints a single counter's contents and timings to chat, with the option to keep it short (so no item breakdown,
+     * only rates). Again, realtime displays IRL time as opposed to in game time.
+     */
     public List<BaseText> format(MinecraftServer server, boolean realTime, boolean brief)
     {
         long ticks = Math.max(realTime ? (System.currentTimeMillis() - startMillis) / 50 : server.getWorld(World.OVERWORLD).getTime() - startTick, 1);  //OW
@@ -172,6 +223,10 @@ public class HopperCounter
         return items;
     }
 
+    /**
+     * Converts a colour to have a low brightness and uniform colour, so when it prints the items in different colours
+     * it's not too flashy and bright, but enough that it's not dull to look at.
+     */
     public static int appropriateColor(int color)
     {
         if (color == 0) return MaterialColor.WHITE.color;
@@ -184,6 +239,10 @@ public class HopperCounter
         return (r << 16) + (g << 8) + b;
     }
 
+    /**
+     * Maps items that don't get a good block to reference for colour, or those that colour is wrong to a number of blocks, so we can get their colours easily with the
+     * {@link Block#getDefaultMaterialColor()} method as these items have those same colours.
+     */
     private static final ImmutableMap<Item, Block> DEFAULTS = new ImmutableMap.Builder<Item, Block>()
             .put(Items.DANDELION, Blocks.YELLOW_WOOL)
             .put(Items.POPPY, Blocks.RED_WOOL)
@@ -269,6 +328,9 @@ public class HopperCounter
             //.put(Items.,Blocks.)
             .build();
 
+    /**
+     * Gets the colour to print an item in when printing its count in a hopper counter.
+     */
     public static TextColor fromItem(Item item)
     {
         if (DEFAULTS.containsKey(item)) return TextColor.fromRgb(appropriateColor(DEFAULTS.get(item).getDefaultMaterialColor().color));
@@ -292,6 +354,10 @@ public class HopperCounter
         return null;
     }
 
+    /**
+     * Guesses the item's colour from the item itself. It first calls {@link HopperCounter#fromItem} to see if it has a
+     * valid colour there, if not just makes a guess, and if that fails just returns null
+     */
     public static TextColor guessColor(Item item)
     {
         TextColor direct = fromItem(item);
@@ -319,6 +385,9 @@ public class HopperCounter
         return null;
     }
 
+    /**
+     * Returns the hopper counter from the colour name, if not null
+     */
     public static HopperCounter getCounter(String color)
     {
         try
@@ -332,6 +401,9 @@ public class HopperCounter
         }
     }
 
+    /**
+     * The total number of items in the counter
+     */
     public long getTotalItems()
     {
         return counter.isEmpty()?0:counter.values().stream().mapToLong(Long::longValue).sum();

src/main/java/carpet/mixins/HopperBlockEntityMixin.java

@@ -16,6 +16,9 @@ import org.spongepowered.asm.mixin.injection.callback.CallbackInfoReturnable;
 import carpet.helpers.HopperCounter;
 import carpet.utils.WoolTool;
 
+/**
+ * The {@link Mixin} which removes items in a hopper if it points into a wool counter, and calls {@link HopperCounter#add}
+ */
 @Mixin(HopperBlockEntity.class)
 public abstract class HopperBlockEntityMixin extends LootableContainerBlockEntity {
 
@@ -36,6 +39,9 @@ public abstract class HopperBlockEntityMixin extends LootableContainerBlockEntit
 
     @Shadow public abstract void setStack(int slot, ItemStack stack);
 
+    /**
+     * A method to remove items from hoppers pointing into wool and count them via {@link HopperCounter#add} method
+     */
     @Inject(method = "insert", at = @At("HEAD"), cancellable = true)
     private void onInsert(CallbackInfoReturnable<Boolean> cir)
     {
@@ -58,4 +64,4 @@ public abstract class HopperBlockEntityMixin extends LootableContainerBlockEntit
             }
         }
     }
-}
+}

src/main/java/carpet/utils/WoolTool.java

@@ -18,10 +18,23 @@ import java.util.ArrayList;
 import java.util.HashMap;
 import java.util.List;
 
+/**
+ * A series of utility functions and variables for dealing predominantly with hopper counters and determining which counter
+ * to add their items to, as well as helping dealing with carpet functionality.
+ */
 public class WoolTool
 {
+    /**
+     * A map of the {@link MaterialColor} to the {@link DyeColor} which is used in {@link WoolTool#getWoolColorAtPosition}
+     * to get the colour of wool at a position.
+     */
     private static final HashMap<MaterialColor,DyeColor> Material2Dye = new HashMap<>();
 
+    /**
+     * A map of all the wool colours to their respective colours in the {@link Messenger#m} format so the name of the counter
+     * gets printed in colour.
+     */
+
     public static final HashMap<MaterialColor,String> Material2DyeName = new HashMap<MaterialColor, String>(){{
         put(MaterialColor.WHITE, "w ");
         put(MaterialColor.ORANGE, "#F9801D ");
@@ -49,6 +62,13 @@ public class WoolTool
         }
     }
 
+    /**
+     * The method which gets triggered when a player places a carpet, and decides what to do based on the carpet's colour:
+     * <ul>
+     *     <li>Red - Resets the counter of the colour of wool underneath the carpet (if there is no wool, then nothing happens)</li>
+     *     <li>Green - Prints the contents of the counter of the colour of wool underneath the carpet</li>
+     * </ul>
+     */
     public static void carpetPlacedAction(DyeColor color, PlayerEntity placer, BlockPos pos, ServerWorld worldIn)
     {
 		if (!CarpetSettings.carpets)
@@ -113,6 +133,9 @@ public class WoolTool
         }
     }
 
+    /**
+     * Gets the colour of wool at the position, for hoppers to be able to decide whether to add their items to the global counter.
+     */
     public static DyeColor getWoolColorAtPosition(World worldIn, BlockPos pos)
     {
         BlockState state = worldIn.getBlockState(pos);