From 720f6985218463f3b5d23a0e362df54b62c6a5ec Mon Sep 17 00:00:00 2001
From: masmc05 <masmc05@gmail.com>
Date: Mon, 23 Dec 2024 11:32:19 +0100
Subject: [PATCH 1/2] Fix Inventory#addItem javadoc mismatch with behaviour

---
 .../src/main/java/org/bukkit/inventory/Inventory.java | 11 +++++------
 1 file changed, 5 insertions(+), 6 deletions(-)

diff --git a/paper-api/src/main/java/org/bukkit/inventory/Inventory.java b/paper-api/src/main/java/org/bukkit/inventory/Inventory.java
index 0d519813c12d..1a0192b06cf6 100644
--- a/paper-api/src/main/java/org/bukkit/inventory/Inventory.java
+++ b/paper-api/src/main/java/org/bukkit/inventory/Inventory.java
@@ -85,12 +85,11 @@ public interface Inventory extends Iterable<ItemStack> {
      * index of the varargs parameter. If all items are stored, it will return
      * an empty HashMap.
      * <p>
-     * If you pass in ItemStacks which exceed the maximum stack size for the
-     * Material, first they will be added to partial stacks where
-     * Material.getMaxStackSize() is not exceeded, up to
-     * Material.getMaxStackSize(). When there are no partial stacks left
-     * stacks will be split on Inventory.getMaxStackSize() allowing you to
-     * exceed the maximum stack size for that material.
+     * The maximum size of the stack added to this inventory will be the minimum
+     * of {@link ItemStack#getMaxStackSize()} and {@link #getMaxStackSize()}.
+     * <p>
+     * First, this method will try to fill the partial stacks in the inventory.
+     * Then, it will try to fill empty slots.
      * <p>
      * It is known that in some implementations this method will also set
      * the inputted argument amount to the number of that item not placed in

From 0c5fe036f3d6fa2abd83a7df5b80e3356413a83b Mon Sep 17 00:00:00 2001
From: masmc05 <masmc05@gmail.com>
Date: Mon, 23 Dec 2024 15:42:33 +0100
Subject: [PATCH 2/2] Try to improve the wording

---
 .../src/main/java/org/bukkit/inventory/Inventory.java      | 7 ++++---
 1 file changed, 4 insertions(+), 3 deletions(-)

diff --git a/paper-api/src/main/java/org/bukkit/inventory/Inventory.java b/paper-api/src/main/java/org/bukkit/inventory/Inventory.java
index 1a0192b06cf6..1cea8361c460 100644
--- a/paper-api/src/main/java/org/bukkit/inventory/Inventory.java
+++ b/paper-api/src/main/java/org/bukkit/inventory/Inventory.java
@@ -85,11 +85,12 @@ public interface Inventory extends Iterable<ItemStack> {
      * index of the varargs parameter. If all items are stored, it will return
      * an empty HashMap.
      * <p>
-     * The maximum size of the stack added to this inventory will be the minimum
+     * Items resulted from this method will not exceed the minimum
      * of {@link ItemStack#getMaxStackSize()} and {@link #getMaxStackSize()}.
      * <p>
-     * First, this method will try to fill the partial stacks in the inventory.
-     * Then, it will try to fill empty slots.
+     * First, this method will try to fill all the partial stacks in the inventory.
+     * Then it will try to fill empty slots, over-stacked items being able to
+     * fill several empty slots. The rest are placed in the returned map.
      * <p>
      * It is known that in some implementations this method will also set
      * the inputted argument amount to the number of that item not placed in