Add documentation for ToolMaterial & ToolItem classes

mappings/net/minecraft/item/ToolItem.mapping

@@ -1,6 +1,23 @@
 CLASS net/minecraft/class_1831 net/minecraft/item/ToolItem
+	COMMENT An {@link Item} used as a tool, typically used for harvesting blocks or killing entities.
+	COMMENT
+	COMMENT <p>
+	COMMENT Each {@link ToolItem} has a {@link ToolMaterial} which defines base tool statistics for it.
+	COMMENT By default, {@link ToolItem#getEnchantability()} and {@link ToolItem#canRepair(ItemStack, ItemStack)} will
+	COMMENT delegate to this material for values. Behavior for other material properties is implemented in {@link net.minecraft.item.MiningToolItem}.
+	COMMENT
+	COMMENT <p>
+	COMMENT A list of default vanilla tool classes can be found below:
+	COMMENT <ul>
+	COMMENT     <li>Sword: {@link net.minecraft.item.SwordItem}</li>
+	COMMENT     <li>Pickaxe: {@link net.minecraft.item.PickaxeItem}</li>
+	COMMENT     <li>Shovel: {@link net.minecraft.item.ShovelItem}</li>
+	COMMENT     <li>Axe: {@link net.minecraft.item.AxeItem}</li>
+	COMMENT     <li>Hoe: {@link net.minecraft.item.HoeItem}</li>
+	COMMENT </ul>
 	FIELD field_8921 material Lnet/minecraft/class_1832;
 	METHOD <init> (Lnet/minecraft/class_1832;Lnet/minecraft/class_1792$class_1793;)V
 		ARG 1 material
 		ARG 2 settings
 	METHOD method_8022 getMaterial ()Lnet/minecraft/class_1832;
+		COMMENT @return the {@link ToolMaterial} used by this {@link ToolItem}

mappings/net/minecraft/item/ToolMaterial.mapping

@@ -1,7 +1,44 @@
 CLASS net/minecraft/class_1832 net/minecraft/item/ToolMaterial
+	COMMENT Defines the material stats of a {@link net.minecraft.item.ToolItem} item.
+	COMMENT <p>
+	COMMENT To view available vanilla tool materials, visit {@link net.minecraft.item.ToolMaterials}.
 	METHOD method_8023 getRepairIngredient ()Lnet/minecraft/class_1856;
+		COMMENT Returns the {@link Ingredient} used to repair items using this {@link ToolMaterial}.
+		COMMENT <p>
+		COMMENT By default, {@link net.minecraft.item.ToolMaterial} will delegate {@link net.minecraft.item.Item#canRepair(ItemStack, ItemStack)}
+		COMMENT back to this method.
+		COMMENT @return the {@link Ingredient} required to repair items with this {@link ToolMaterial}
 	METHOD method_8024 getMiningLevel ()I
+		COMMENT Returns the mining level of a {@link net.minecraft.item.ToolItem} using this {@link ToolMaterial}.
+		COMMENT To prevent this tool from succesfully harvesting any mining level gated blocks, return {@link net.fabricmc.yarn.constants.MiningLevels#HAND}.
+		COMMENT <p>
+		COMMENT For more information on mining levels, visit {@link net.fabricmc.yarn.constants.MiningLevels}.
+		COMMENT @return the mining level of a {@link net.minecraft.item.ToolItem} using this {@link ToolMaterial}
 	METHOD method_8025 getDurability ()I
+		COMMENT Returns the total amount of durability a {@link net.minecraft.item.ToolItem} using this {@link ToolMaterial} has.
+		COMMENT <p>
+		COMMENT The value returned here will set the {@link net.minecraft.item.Item.Settings} max durability option when passed
+		COMMENT into {@link net.minecraft.item.ToolItem#ToolItem(net.minecraft.item.ToolMaterial, net.minecraft.item.Item.Settings)}
+		COMMENT if the value was not already specified.
+		COMMENT @return the total durability a {@link net.minecraft.item.ToolItem} with this {@link ToolMaterial} has
 	METHOD method_8026 getEnchantability ()I
+		COMMENT Returns the base enchantment value used by {@link ToolMaterial} with this material.
+		COMMENT <p>
+		COMMENT By default, {@link ToolMaterial} will override {@link net.minecraft.item.Item#getEnchantability()}
+		COMMENT and delegate the call back to this method.
+		COMMENT <p>
+		COMMENT A higher return value will result in better enchantment results when using an {@code Enchanting Table}.
+		COMMENT The highest enchantability value in vanilla is Netherite, at {@code 37}.
+		COMMENT @return the enchantment value sent back to {@link net.minecraft.item.Item#getEnchantability()} for armor using this material
 	METHOD method_8027 getMiningSpeedMultiplier ()F
+		COMMENT Returns the mining speed bonus applied when a {@link net.minecraft.item.ToolItem} using this material is breaking an appropriate block.
+		COMMENT {@code 1.0f} will result in no speed change.
+		COMMENT <p>
+		COMMENT <b>Note:</b> for default vanilla tool classes, this bonus is only applied in {@link net.minecraft.item.MiningToolItem#getMiningSpeedMultiplier(ItemStack, BlockState)}.
+		COMMENT @return the mining speed bonus applied when a {@link net.minecraft.item.ToolItem} using this material is breaking an appropriate block, with {@code 1.0f} being no change
 	METHOD method_8028 getAttackDamage ()F
+		COMMENT Returns the attack damage bonus applied to any {@link net.minecraft.item.ToolItem} using this {@link ToolMaterial}.
+		COMMENT <p>
+		COMMENT In the case of {@link net.minecraft.item.MiningToolItem} or {@link net.minecraft.item.SwordItem}, the value returned
+		COMMENT here will be added on top of the {@code attackDamage} value passed into the tool's constructor.
+		COMMENT @return the attack damage bonus applied to any {@link net.minecraft.item.ToolItem} using this {@link ToolMaterial}

mappings/net/minecraft/item/ToolMaterials.mapping

@@ -1,4 +1,5 @@
 CLASS net/minecraft/class_1834 net/minecraft/item/ToolMaterials
+	COMMENT Provides the default {@link ToolMaterial}s used by vanilla tools.
 	FIELD field_8924 itemDurability I
 	FIELD field_8925 miningLevel I
 	FIELD field_8928 repairIngredient Lnet/minecraft/class_3528;