Document TradeOffer and improve various names (#2139)

* Document TradeOffer and improve various names

* Update mappings/net/minecraft/village/TradeOffer.mapping

Co-authored-by: liach <7806504+liach@users.noreply.github.com>

Co-authored-by: liach <7806504+liach@users.noreply.github.com>

mappings/net/minecraft/entity/passive/VillagerEntity.mapping

@@ -36,14 +36,15 @@ CLASS net/minecraft/class_1646 net/minecraft/entity/passive/VillagerEntity
 	METHOD method_19182 restock ()V
 	METHOD method_19183 playWorkSound ()V
 	METHOD method_19185 consumeAvailableFood ()V
-	METHOD method_19187 clearCurrentBonus ()V
+	METHOD method_19187 clearSpecialPrices ()V
+		COMMENT Resets the special price of all the trade offers of this villager.
 	METHOD method_19188 canLevelUp ()Z
 	METHOD method_19189 getAvailableFood ()I
 	METHOD method_19190 spawnIronGolem (Lnet/minecraft/class_3218;)Lnet/minecraft/class_1439;
 		ARG 1 world
 	METHOD method_19191 beginTradeWith (Lnet/minecraft/class_1657;)V
 		ARG 1 customer
-	METHOD method_19192 prepareRecipesFor (Lnet/minecraft/class_1657;)V
+	METHOD method_19192 prepareOffersFor (Lnet/minecraft/class_1657;)V
 		ARG 1 player
 	METHOD method_19193 depleteFood (I)V
 		ARG 1 amount
@@ -67,13 +68,17 @@ CLASS net/minecraft/class_1646 net/minecraft/entity/passive/VillagerEntity
 		ARG 1 worldTime
 	METHOD method_20821 clearDailyRestockCount ()V
 	METHOD method_20822 shouldRestock ()Z
-	METHOD method_20823 needRestock ()Z
+	METHOD method_20823 needsRestock ()Z
+		COMMENT Returns whether this villager needs restock.
+		COMMENT
+		COMMENT <p>Checks if at least one of its trade offers has been used.
 	METHOD method_20824 canRestock ()Z
 	METHOD method_21650 setGossipDataFromNbt (Lnet/minecraft/class_2520;)V
 		ARG 1 tag
 	METHOD method_21651 getGossip ()Lnet/minecraft/class_4136;
-	METHOD method_21723 restockAndUpdatePricesOnDemand ()V
+	METHOD method_21723 restockAndUpdateDemandBonus ()V
-	METHOD method_21724 updatePricesOnDemand ()V
+	METHOD method_21724 updateDemandBonus ()V
+		COMMENT Updates the demand bonus of all the trade offers of this villager.
 	METHOD method_26955 createVillagerAttributes ()Lnet/minecraft/class_5132$class_5133;
 	METHOD method_29279 isNatural ()Z
 	METHOD method_30023 getHighestOpenPositionOnOffset (Lnet/minecraft/class_2338;DD)Lnet/minecraft/class_2338;

mappings/net/minecraft/village/Merchant.mapping

@@ -1,4 +1,8 @@
 CLASS net/minecraft/class_1915 net/minecraft/village/Merchant
+	METHOD method_17448 (ILnet/minecraft/class_1661;Lnet/minecraft/class_1657;)Lnet/minecraft/class_1703;
+		ARG 1 syncId
+		ARG 2 playerInventory
+		ARG 3 player
 	METHOD method_17449 sendOffers (Lnet/minecraft/class_1657;Lnet/minecraft/class_2561;I)V
 		ARG 1 player
 		ARG 2 test

mappings/net/minecraft/village/MerchantInventory.mapping

@@ -1,6 +1,6 @@
 CLASS net/minecraft/class_1725 net/minecraft/village/MerchantInventory
 	FIELD field_18668 merchantRewardedExperience I
-	FIELD field_7842 recipeIndex I
+	FIELD field_7842 offerIndex I
 	FIELD field_7843 tradeOffer Lnet/minecraft/class_1914;
 	FIELD field_7844 merchant Lnet/minecraft/class_1915;
 	FIELD field_7845 inventory Lnet/minecraft/class_2371;
@@ -8,8 +8,8 @@ CLASS net/minecraft/class_1725 net/minecraft/village/MerchantInventory
 		ARG 1 merchant
 	METHOD method_19252 getMerchantRewardedExperience ()I
 	METHOD method_7642 getTradeOffer ()Lnet/minecraft/class_1914;
-	METHOD method_7643 setRecipeIndex (I)V
+	METHOD method_7643 setOfferIndex (I)V
 		ARG 1 index
-	METHOD method_7644 needRecipeUpdate (I)Z
+	METHOD method_7644 needsOfferUpdate (I)Z
 		ARG 1 slot
-	METHOD method_7645 updateRecipes ()V
+	METHOD method_7645 updateOffers ()V

mappings/net/minecraft/village/SimpleMerchant.mapping

@@ -1,6 +1,6 @@
 CLASS net/minecraft/class_1645 net/minecraft/village/SimpleMerchant
 	FIELD field_18525 experience I
 	FIELD field_7441 player Lnet/minecraft/class_1657;
-	FIELD field_7442 recipeList Lnet/minecraft/class_1916;
+	FIELD field_7442 offers Lnet/minecraft/class_1916;
 	METHOD <init> (Lnet/minecraft/class_1657;)V
 		ARG 1 player

mappings/net/minecraft/village/TradeOffer.mapping

@@ -13,14 +13,14 @@ CLASS net/minecraft/class_1914 net/minecraft/village/TradeOffer
 		ARG 1 buyItem
 		ARG 2 sellItem
 		ARG 3 maxUses
-		ARG 4 rewardedExp
+		ARG 4 merchantExperience
 		ARG 5 priceMultiplier
 	METHOD <init> (Lnet/minecraft/class_1799;Lnet/minecraft/class_1799;Lnet/minecraft/class_1799;IIF)V
 		ARG 1 firstBuyItem
 		ARG 2 secondBuyItem
 		ARG 3 sellItem
 		ARG 4 maxUses
-		ARG 5 rewardedExp
+		ARG 5 merchantExperience
 		ARG 6 priceMultiplier
 	METHOD <init> (Lnet/minecraft/class_1799;Lnet/minecraft/class_1799;Lnet/minecraft/class_1799;IIIF)V
 		ARG 1 firstBuyItem
@@ -28,7 +28,7 @@ CLASS net/minecraft/class_1914 net/minecraft/village/TradeOffer
 		ARG 3 sellItem
 		ARG 4 uses
 		ARG 5 maxUses
-		ARG 6 rewardedExp
+		ARG 6 merchantExperience
 		ARG 7 priceMultiplier
 	METHOD <init> (Lnet/minecraft/class_1799;Lnet/minecraft/class_1799;Lnet/minecraft/class_1799;IIIFI)V
 		ARG 1 firstBuyItem
@@ -36,7 +36,7 @@ CLASS net/minecraft/class_1914 net/minecraft/village/TradeOffer
 		ARG 3 sellItem
 		ARG 4 uses
 		ARG 5 maxUses
-		ARG 6 rewardedExp
+		ARG 6 merchantExperience
 		ARG 7 priceMultiplier
 		ARG 8 demandBonus
 	METHOD <init> (Lnet/minecraft/class_2487;)V
@@ -50,27 +50,77 @@ CLASS net/minecraft/class_1914 net/minecraft/village/TradeOffer
 	METHOD method_16954 acceptsBuy (Lnet/minecraft/class_1799;Lnet/minecraft/class_1799;)Z
 		ARG 1 given
 		ARG 2 sample
-	METHOD method_18019 getSellItem ()Lnet/minecraft/class_1799;
+	METHOD method_18019 copySellItem ()Lnet/minecraft/class_1799;
+		COMMENT Returns a copy of the sell item of this trade offer.
 	METHOD method_19272 getAdjustedFirstBuyItem ()Lnet/minecraft/class_1799;
+		COMMENT Returns a copy of the first buy item of this trade offer,
+		COMMENT with its price adjusted depending on the demand bonus, the
+		COMMENT special price and the price multiplier.
 	METHOD method_19273 setSpecialPrice (I)V
+		COMMENT Sets the special price of this trade offer to {@code specialPrice}.
 		ARG 1 specialPrice
-	METHOD method_19274 updatePriceOnDemand ()V
+	METHOD method_19274 updateDemandBonus ()V
+		COMMENT Updates the demand bonus of this trade offer depending on its
+		COMMENT previous demand bonus, the number of times it has been used and
+		COMMENT its remaining uses.
 	METHOD method_19275 resetUses ()V
+		COMMENT Resets the number of times this trade offer has been used.
 	METHOD method_19276 clearSpecialPrice ()V
+		COMMENT Resets the special price of this trade offer.
 	METHOD method_19277 getSpecialPrice ()I
+		COMMENT Returns the special price of this trade offer. It is used to
+		COMMENT adjust the price of its first buy item.
+		COMMENT
+		COMMENT <p>The less the special price is, the more the price will be low.
 	METHOD method_19278 getPriceMultiplier ()F
+		COMMENT Returns the price multiplier of this trade offer. It is used to
+		COMMENT adjust the price of its first buy item.
 	METHOD method_19279 getMerchantExperience ()I
+		COMMENT Returns the amount of experience that will be given to a merchant
+		COMMENT after this trade offer has been used.
 	METHOD method_21725 getDemandBonus ()I
-	METHOD method_21834 hasAvailableUses ()Z
+		COMMENT Returns the demand bonus of this trade offer. It is used to
+		COMMENT adjust the price of its first buy item.
+		COMMENT
+		COMMENT <p>The more the demand bonus is, the more the price will be high.
+		COMMENT
+		COMMENT <p>It is updated when a villager restocks.
+		COMMENT
+		COMMENT @see #updateDemandBonus()
+	METHOD method_21834 hasBeenUsed ()Z
+		COMMENT Returns whether this trade offer has already been used.
+		COMMENT
+		COMMENT <p>Checks if the number of times this trade offer has been used
+		COMMENT is greater than 0.
 	METHOD method_8244 use ()V
+		COMMENT Increments the number of times this trade offer has been used.
 	METHOD method_8245 increaseSpecialPrice (I)V
+		COMMENT Increases the special price of this trade offer by {@code increment}.
+		COMMENT
+		COMMENT <p>A negative {@code increment} value will decrease the special price.
 		ARG 1 increment
 	METHOD method_8246 getOriginalFirstBuyItem ()Lnet/minecraft/class_1799;
+		COMMENT Returns the first buy item of this trade offer.
 	METHOD method_8247 getSecondBuyItem ()Lnet/minecraft/class_1799;
+		COMMENT Returns the second buy item of this trade offer.
+		COMMENT
+		COMMENT <p>If there is no second buy item, this returns the {@linkplain ItemStack#EMPTY empty
+		COMMENT item stack}.
 	METHOD method_8248 getMaxUses ()I
+		COMMENT Returns the maximum number of times this trade offer can be used.
 	METHOD method_8249 getUses ()I
-	METHOD method_8250 getMutableSellItem ()Lnet/minecraft/class_1799;
+		COMMENT Returns the number of times this trade offer has been used.
+	METHOD method_8250 getSellItem ()Lnet/minecraft/class_1799;
+		COMMENT Returns the sell item of this trade offer.
 	METHOD method_8251 toNbt ()Lnet/minecraft/class_2487;
-	METHOD method_8254 clearUses ()V
+	METHOD method_8254 disable ()V
+		COMMENT Sets the number of times this trade offer has been used to
+		COMMENT its maximum uses, making it disabled.
 	METHOD method_8255 isDisabled ()Z
+		COMMENT Returns whether this trade offer is disabled.
+		COMMENT
+		COMMENT <p>Checks if the number of times this trade offer has been used
+		COMMENT is greater or equal to its maximum uses.
 	METHOD method_8256 shouldRewardPlayerExperience ()Z
+		COMMENT Returns whether experience should be given to a player when
+		COMMENT they use this trade offer.

mappings/net/minecraft/village/TradeOfferList.mapping

@@ -2,11 +2,11 @@ CLASS net/minecraft/class_1916 net/minecraft/village/TradeOfferList
 	METHOD <init> (Lnet/minecraft/class_2487;)V
 		ARG 1 nbt
 	METHOD method_8265 fromPacket (Lnet/minecraft/class_2540;)Lnet/minecraft/class_1916;
-		ARG 0 byteBuf
+		ARG 0 buf
 	METHOD method_8267 getValidOffer (Lnet/minecraft/class_1799;Lnet/minecraft/class_1799;I)Lnet/minecraft/class_1914;
 		ARG 1 firstBuyItem
 		ARG 2 secondBuyItem
 		ARG 3 index
 	METHOD method_8268 toNbt ()Lnet/minecraft/class_2487;
 	METHOD method_8270 toPacket (Lnet/minecraft/class_2540;)V
-		ARG 1 buffer
+		ARG 1 buf