Document code

src/dev/w1zzrd/invtweaks/InvTweaksPlugin.java

@@ -16,6 +16,9 @@ import java.util.logging.Logger;
  */
 public final class InvTweaksPlugin extends JavaPlugin {
 
+    /**
+     * Plugin logging tag. This should be prepended to any log messages sent by this plugin
+     */
     public static final String LOG_PLUGIN_NAME = "[InvTweaks]";
 
     private final Logger logger = Bukkit.getLogger();
@@ -38,10 +41,16 @@ public final class InvTweaksPlugin extends JavaPlugin {
     }
 
 
+    /**
+     * Initialize commands registered by this plugin
+     */
     private void initCommands() {
         Objects.requireNonNull(getCommand("sort")).setExecutor(new SortCommandExecutor());
     }
 
+    /**
+     * Initialize event listeners for this plugin
+     */
     private void initEvents() {
         final PluginManager pluginManager = getServer().getPluginManager();
 

src/dev/w1zzrd/invtweaks/command/SortCommandExecutor.java

@@ -122,6 +122,7 @@ public class SortCommandExecutor implements CommandExecutor {
         logger.fine(LOG_PLUGIN_NAME + " Sorting player");
         final ItemStack[] stacks = player.getInventory().getContents();
 
+        // Get sortable subset of players inventory (main inventory, sans hotbar)
         final ItemStack[] sortable = Arrays.copyOfRange(stacks, 9, 36);
         organizeStacks(sortable);
         System.arraycopy(sortable, 0, stacks, 9, sortable.length);
@@ -183,23 +184,29 @@ public class SortCommandExecutor implements CommandExecutor {
      */
     private static void mergeStacks(final ItemStack[] stacks) {
         final HashMap<ItemStack, Integer> count = new HashMap<>();
+
+        // First pass counts total amount of items for each unique stack type
         for (final ItemStack stack : stacks) {
             if (stack == null)
                 continue;
 
+            // Check if an instance of the current ItemStack already occurred earlier in the pass
             final Optional<ItemStack> tracked = count.keySet().stream().filter(stack::isSimilar).findFirst();
 
             if (tracked.isPresent())
-                count.put(tracked.get(), count.get(tracked.get()) + stack.getAmount());
+                count.put(tracked.get(), count.get(tracked.get()) + stack.getAmount()); // Increment existing count
             else
-                count.put(stack, stack.getAmount());
+                count.put(stack, stack.getAmount());                                    // Start a new count
         }
 
+        // Second pass collects stacks such that, at most, only one stack for
+        // each type will not be holding the maximum stack size after the pass is done
         for (int i = stacks.length - 1; i >= 0; --i) {
             final ItemStack current = stacks[i];
             if (current == null)
                 continue;
 
+            // Since each item in the inventory should be tracked from the first pass, this should always hold a value
             final Optional<ItemStack> tracked = count.keySet().stream().filter(current::isSimilar).findFirst();
 
             // Should always be true but I don't know Spigot, so I'm gonna play it safe
@@ -210,6 +217,7 @@ public class SortCommandExecutor implements CommandExecutor {
                 if (amount == 0) {
                     stacks[i] = null;
                 } else {
+                    // Set the stack to the highest possible value within the stack size and remaining-items constraints
                     final int newAmount = Math.min(amount, current.getMaxStackSize());
                     current.setAmount(newAmount);
 

src/dev/w1zzrd/invtweaks/listener/SortListener.java

@@ -22,6 +22,12 @@ public class SortListener implements Listener {
         final PlayerInventory playerInventory = event.getPlayer().getInventory();
 
 
+        /* Criteria for a successful /sort trigger (in order of occurrence in code):
+         *   1. Player must be attempting to interact with a block
+         *   2. Player must be attempting to interact with a Chest or Shulker Box
+         *   3. Player must be sneaking
+         *   4. Player must be holding a sword in their main hand
+         */
         if (event.hasBlock() &&
                 (Objects.requireNonNull(event.getClickedBlock()).getState() instanceof Chest ||
                         event.getClickedBlock().getState() instanceof ShulkerBox) &&

src/dev/w1zzrd/invtweaks/package-info.java

@@ -0,0 +1,15 @@
+/**
+ * Spigot MC Inventory Tweaks plugin:<br>
+ * A plugin aimed at providing minor, inventory-related tweaks to improve the
+ * Minecraft experience<br><br>
+ * <h3>Commands</h3>
+ * <pre>
+ * /sort    Sort a targeted chest or shulker box or the senders inventory if
+ *          aforementioned blocks aren't targeted
+ * </pre>
+ * <h3>Features</h3>
+ * <ul>
+ *     <li>Sneak + right-click inventory with sword to trigger /sort</li>
+ * </ul>
+ */
+package dev.w1zzrd.invtweaks;