Add some Inventory addItem / removeItem notes

By: md_5 <git@md-5.net>

paper-api/src/main/java/org/bukkit/inventory/Inventory.java

@@ -85,6 +85,10 @@ public interface Inventory extends Iterable<ItemStack> {
      * 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.
+     * <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
+     * slots.
      *
      * @param items The ItemStacks to add
      * @return A HashMap containing items that didn't fit.
@@ -102,6 +106,10 @@ public interface Inventory extends Iterable<ItemStack> {
      * the index of the parameter, and the value is the ItemStack at that
      * index of the varargs parameter. If all the given ItemStacks are
      * removed, it will return an empty HashMap.
+     * <p>
+     * It is known that in some implementations this method will also set the
+     * inputted argument amount to the number of that item not removed from
+     * slots.
      *
      * @param items The ItemStacks to remove
      * @return A HashMap containing items that couldn't be removed.