SPIGOT-5766: Updates related to the villager trading changes introduced in MC 1.14.

* The VillagerReplenishTradeEvent is now called whenever a villager restocks one of its trades. Previously, it was called in some (but not all) cases in which a villager updates the special price values of its merchant recipes.
* VillagerReplenishTradeEvent#get/setBonus have been deprecated and #setBonus has no effect anymore. The way villagers restock their trades has changed in MC 1.14: Instead of adjusting the max uses of their trades, they reset their uses to 0. #getBonus returns the value of MerchantRecipe#getUses now.
* Updated various outdated and inaccurate javadoc in MerchantRecipe.

By: blablubbabc <lukas@wirsindwir.de>

paper-api/src/main/java/org/bukkit/event/entity/VillagerReplenishTradeEvent.java

@@ -1,16 +1,18 @@
 package org.bukkit.event.entity;
 
 import org.bukkit.entity.AbstractVillager;
+import org.bukkit.entity.Villager;
 import org.bukkit.event.Cancellable;
 import org.bukkit.event.HandlerList;
 import org.bukkit.inventory.MerchantRecipe;
 import org.jetbrains.annotations.NotNull;
 
 /**
- * Called when a villager's trade's maximum uses is increased, due to a player's
- * trade.
- *
- * @see MerchantRecipe#getMaxUses()
+ * Called when a {@link Villager} is about to restock one of its trades.
+ * <p>
+ * If this event passes, the villager will reset the
+ * {@link MerchantRecipe#getUses() uses} of the affected {@link #getRecipe()
+ * MerchantRecipe} to <code>0</code>.
  */
 public class VillagerReplenishTradeEvent extends EntityEvent implements Cancellable {
 
@@ -18,12 +20,10 @@ public class VillagerReplenishTradeEvent extends EntityEvent implements Cancella
     private boolean cancelled;
     //
     private MerchantRecipe recipe;
-    private int bonus;
 
-    public VillagerReplenishTradeEvent(@NotNull AbstractVillager what, @NotNull MerchantRecipe recipe, int bonus) {
+    public VillagerReplenishTradeEvent(@NotNull AbstractVillager what, @NotNull MerchantRecipe recipe) {
         super(what);
         this.recipe = recipe;
-        this.bonus = bonus;
     }
 
     /**
@@ -46,23 +46,26 @@ public class VillagerReplenishTradeEvent extends EntityEvent implements Cancella
     }
 
     /**
-     * Get the bonus uses added. The maximum uses of the recipe will be
-     * increased by this number.
+     * Get the bonus uses added.
      *
      * @return the extra uses added
+     * @deprecated MC 1.14 has changed how villagers restock their trades. Use
+     * {@link MerchantRecipe#getUses()}.
      */
+    @Deprecated
     public int getBonus() {
-        return bonus;
+        return recipe.getUses();
     }
 
     /**
      * Set the bonus uses added.
      *
      * @param bonus the extra uses added
-     * @see VillagerReplenishTradeEvent#getBonus()
+     * @deprecated MC 1.14 has changed how villagers restock their trades. This
+     * has no effect anymore.
      */
+    @Deprecated
     public void setBonus(int bonus) {
-        this.bonus = bonus;
     }
 
     @Override

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

@@ -4,7 +4,7 @@ import com.google.common.base.Preconditions;
 import java.util.ArrayList;
 import java.util.List;
 import org.bukkit.Material;
-import org.bukkit.event.entity.VillagerReplenishTradeEvent;
+import org.bukkit.entity.Villager;
 import org.bukkit.potion.PotionEffectType;
 import org.bukkit.util.NumberConversions;
 import org.jetbrains.annotations.NotNull;
@@ -12,16 +12,16 @@ import org.jetbrains.annotations.Nullable;
 
 /**
  * Represents a merchant's trade.
- *
+ * <p>
  * Trades can take one or two ingredients, and provide one result. The
  * ingredients' ItemStack amounts are respected in the trade.
- * <br>
- * A trade has a limited number of uses, after which the trade can no longer be
- * used, unless the player uses a different trade, which will cause its maximum
- * uses to increase.
- * <br>
+ * <p>
+ * A trade has a maximum number of uses. A {@link Villager} may periodically
+ * replenish its trades by resetting the {@link #getUses uses} of its merchant
+ * recipes to <code>0</code>, allowing them to be used again.
+ * <p>
  * A trade may or may not reward experience for being completed.
- * <br>
+ * <p>
  * During trades, the {@link MerchantRecipe} dynamically adjusts the amount of
  * its first ingredient based on the following criteria:
  * <ul>
@@ -45,8 +45,6 @@ import org.jetbrains.annotations.Nullable;
  * integer value greater than or equal to 0, and the special price, and then
  * constraining the resulting value between <code>1</code> and the item stack's
  * {@link ItemStack#getMaxStackSize() maximum stack size}.
- *
- * @see org.bukkit.event.entity.VillagerReplenishTradeEvent
  */
 public class MerchantRecipe implements Recipe {
 
@@ -159,20 +157,18 @@ public class MerchantRecipe implements Recipe {
     }
 
     /**
-     * Get the value of the demand for the item in {@link #getResult()}.
+     * Get the demand for this trade.
      *
-     * @return the demand for the item
+     * @return the demand
      */
     public int getDemand() {
         return demand;
     }
 
     /**
-     * Set the value of the demand for the item in {@link #getResult()}.
-     * <br>
-     * <b>Note: </b> This value is updated when the item is purchase
+     * Set the demand for this trade.
      *
-     * @param demand demand value
+     * @param demand the new demand
      */
     public void setDemand(int demand) {
         this.demand = demand;
@@ -180,10 +176,6 @@ public class MerchantRecipe implements Recipe {
 
     /**
      * Get the special price for this trade.
-     * <br>
-     * <b>Note: </b> This value can be updated by
-     * {@link VillagerReplenishTradeEvent#getBonus()} or by
-     * {@link PotionEffectType#HERO_OF_THE_VILLAGE}
      *
      * @return special price value
      */
@@ -192,11 +184,7 @@ public class MerchantRecipe implements Recipe {
     }
 
     /**
-     * Set the special value for this trade.
-     * <br>
-     * <b>Note: </b> This value can be updated by
-     * {@link VillagerReplenishTradeEvent#getBonus()} or by
-     * {@link PotionEffectType#HERO_OF_THE_VILLAGE}
+     * Set the special price for this trade.
      *
      * @param specialPrice special price value
      */
@@ -224,9 +212,6 @@ public class MerchantRecipe implements Recipe {
 
     /**
      * Get the maximum number of uses this trade has.
-     * <br>
-     * The maximum uses of this trade may increase when a player trades with the
-     * owning merchant.
      *
      * @return the maximum number of uses
      */
@@ -282,7 +267,7 @@ public class MerchantRecipe implements Recipe {
     }
 
     /**
-     * Gets the additive price multiplier for the cost of this trade.
+     * Gets the price multiplier for the cost of this trade.
      *
      * @return price multiplier
      */
@@ -291,7 +276,7 @@ public class MerchantRecipe implements Recipe {
     }
 
     /**
-     * Sets the additive price multiplier for the cost of this trade.
+     * Sets the price multiplier for the cost of this trade.
      *
      * @param priceMultiplier new price multiplier
      */