PaperMC/patches/api/Fix-upstream-javadocs.patch

From 0000000000000000000000000000000000000000 Mon Sep 17 00:00:00 2001
From: Zach Brown <1254957+zachbr@users.noreply.github.com>
Date: Sat, 10 Jun 2017 16:59:40 -0500
Subject: [PATCH] Fix upstream javadocs


diff --git a/src/main/java/org/bukkit/BanList.java b/src/main/java/org/bukkit/BanList.java
index 0000000000000000000000000000000000000000..0000000000000000000000000000000000000000 100644
--- a/src/main/java/org/bukkit/BanList.java
+++ b/src/main/java/org/bukkit/BanList.java
@@ -0,0 +0,0 @@ public interface BanList<T> {
 
     /**
      * Gets a {@link BanEntry} by target.
+     * <p>
+     * Bans by name for ban type {@link Type#NAME NAME} are no longer supported and this method will return
+     * null when trying to request them. The replacement is bans by UUID.
      *
      * @param target entry parameter to search for
      * @return the corresponding entry, or null if none found
@@ -0,0 +0,0 @@ public interface BanList<T> {
     /**
      * Adds a ban to this list. If a previous ban exists, this will
      * update the previous entry.
+     * <p>
+     * Bans by name for ban type {@link Type#NAME NAME} are no longer supported and this method will return
+     * null when trying to request them. The replacement is bans by UUID.
      *
      * @param target the target of the ban
      * @param reason reason for the ban, null indicates implementation default
@@ -0,0 +0,0 @@ public interface BanList<T> {
     /**
      * Gets if a {@link BanEntry} exists for the target, indicating an active
      * ban status.
+     * <p>
+     * Bans by name for ban type {@link Type#NAME NAME} are no longer supported.
+     * The replacement is bans by UUID.
      *
      * @param target the target to find
      * @return true if a {@link BanEntry} exists for the target, indicating an
@@ -0,0 +0,0 @@ public interface BanList<T> {
     /**
      * Removes the specified target from this list, therefore indicating a
      * "not banned" status.
+     * <p>
+     * Bans by name for ban type {@link Type#NAME NAME} are no longer supported.
+     * The replacement is bans by UUID.
      *
      * @param target the target to remove from this list
      */
diff --git a/src/main/java/org/bukkit/Bukkit.java b/src/main/java/org/bukkit/Bukkit.java
index 0000000000000000000000000000000000000000..0000000000000000000000000000000000000000 100644
--- a/src/main/java/org/bukkit/Bukkit.java
+++ b/src/main/java/org/bukkit/Bukkit.java
@@ -0,0 +0,0 @@ public final class Bukkit {
 
     /**
      * Gets every player that has ever played on this server.
+     * <p>
+     * <b>This method can be expensive as it loads all the player data files from the disk.</b>
      *
      * @return an array containing all previous players
      */
diff --git a/src/main/java/org/bukkit/ChunkSnapshot.java b/src/main/java/org/bukkit/ChunkSnapshot.java
index 0000000000000000000000000000000000000000..0000000000000000000000000000000000000000 100644
--- a/src/main/java/org/bukkit/ChunkSnapshot.java
+++ b/src/main/java/org/bukkit/ChunkSnapshot.java
@@ -0,0 +0,0 @@ public interface ChunkSnapshot {
      * Get raw biome temperature at given coordinates
      *
      * @param x X-coordinate (0-15)
-     * @param y Y-coordinate (0-15)
+     * @param y Y-coordinate (world minHeight (inclusive) - world maxHeight (exclusive))
      * @param z Z-coordinate (0-15)
      * @return temperature at given coordinate
      */
diff --git a/src/main/java/org/bukkit/Particle.java b/src/main/java/org/bukkit/Particle.java
index 0000000000000000000000000000000000000000..0000000000000000000000000000000000000000 100644
--- a/src/main/java/org/bukkit/Particle.java
+++ b/src/main/java/org/bukkit/Particle.java
@@ -0,0 +0,0 @@ public enum Particle implements Keyed {
     }
 
     /**
-     * Options which can be applied to redstone dust particles - a particle
+     * Options which can be applied to dust particles - a particle
      * color and size.
      */
     public static class DustOptions {
diff --git a/src/main/java/org/bukkit/RegionAccessor.java b/src/main/java/org/bukkit/RegionAccessor.java
index 0000000000000000000000000000000000000000..0000000000000000000000000000000000000000 100644
--- a/src/main/java/org/bukkit/RegionAccessor.java
+++ b/src/main/java/org/bukkit/RegionAccessor.java
@@ -0,0 +0,0 @@ public interface RegionAccessor {
      * Creates a tree at the given {@link Location}
      *
      * @param location Location to spawn the tree
-     * @param random Random to use to generated the tree
+     * @param random Random to use to generate the tree
      * @param type Type of the tree to create
      * @return true if the tree was created successfully, otherwise false
      */
@@ -0,0 +0,0 @@ public interface RegionAccessor {
      * The provided consumer gets called for every block which gets changed
      * as a result of the tree generation. When the consumer gets called no
      * modifications to the world are done yet. Which means, that calling
-     * {@link #getBlockState(Location)} in the consumer while return the state
+     * {@link #getBlockState(Location)} in the consumer will return the state
      * of the block before the generation.
      * <p>
      * Modifications done to the {@link BlockState} in the consumer are respected,
      * which means that it is not necessary to call {@link BlockState#update()}
      *
      * @param location Location to spawn the tree
-     * @param random Random to use to generated the tree
+     * @param random Random to use to generate the tree
      * @param type Type of the tree to create
      * @param stateConsumer The consumer which should get called for every block which gets changed
      * @return true if the tree was created successfully, otherwise false
@@ -0,0 +0,0 @@ public interface RegionAccessor {
      * If it returns {@code false} the block won't get set in the world.
      *
      * @param location Location to spawn the tree
-     * @param random Random to use to generated the tree
+     * @param random Random to use to generate the tree
      * @param type Type of the tree to create
      * @param statePredicate The predicate which should get used to test if a block should be set or not.
      * @return true if the tree was created successfully, otherwise false
diff --git a/src/main/java/org/bukkit/Server.java b/src/main/java/org/bukkit/Server.java
index 0000000000000000000000000000000000000000..0000000000000000000000000000000000000000 100644
--- a/src/main/java/org/bukkit/Server.java
+++ b/src/main/java/org/bukkit/Server.java
@@ -0,0 +0,0 @@ public interface Server extends PluginMessageRecipient, net.kyori.adventure.audi
      * </ul>
      * <p>
      * <b>Note:</b> If set to 0, {@link SpawnCategory} mobs spawning will be disabled.
-     * <p>
-     * Minecraft default: 1.
-     * <br>
-     * <b>Note: </b> the {@link SpawnCategory#MISC} are not consider.
      *
      * @param spawnCategory the category of spawn
      * @return the default ticks per {@link SpawnCategory} mobs spawn value
+     * @throws IllegalArgumentException if the category is {@link SpawnCategory#MISC}
      */
     public int getTicksPerSpawns(@NotNull SpawnCategory spawnCategory);
 
@@ -0,0 +0,0 @@ public interface Server extends PluginMessageRecipient, net.kyori.adventure.audi
 
     /**
      * Gets every player that has ever played on this server.
+     * <p>
+     * <b>This method can be expensive as it loads all the player data files from the disk.</b>
      *
      * @return an array containing all previous players
      */
diff --git a/src/main/java/org/bukkit/World.java b/src/main/java/org/bukkit/World.java
index 0000000000000000000000000000000000000000..0000000000000000000000000000000000000000 100644
--- a/src/main/java/org/bukkit/World.java
+++ b/src/main/java/org/bukkit/World.java
@@ -0,0 +0,0 @@ public interface World extends RegionAccessor, WorldInfo, PluginMessageRecipient
     /**
      * Find the closest nearby structure of a given {@link StructureType}.
      * Finding unexplored structures can, and will, block if the world is
-     * looking in chunks that gave not generated yet. This can lead to the world
+     * looking in chunks that have not generated yet. This can lead to the world
      * temporarily freezing while locating an unexplored structure.
      * <p>
      * The {@code radius} is not a rigid square radius. Each structure may alter
@@ -0,0 +0,0 @@ public interface World extends RegionAccessor, WorldInfo, PluginMessageRecipient
     /**
      * Find the closest nearby structure of a given {@link StructureType}.
      * Finding unexplored structures can, and will, block if the world is
-     * looking in chunks that gave not generated yet. This can lead to the world
+     * looking in chunks that have not generated yet. This can lead to the world
      * temporarily freezing while locating an unexplored structure.
      * <p>
      * The {@code radius} is not a rigid square radius. Each structure may alter
@@ -0,0 +0,0 @@ public interface World extends RegionAccessor, WorldInfo, PluginMessageRecipient
     /**
      * Find the closest nearby structure of a given {@link Structure}. Finding
      * unexplored structures can, and will, block if the world is looking in
-     * chunks that gave not generated yet. This can lead to the world
+     * chunks that have not generated yet. This can lead to the world
      * temporarily freezing while locating an unexplored structure.
      * <p>
      * The {@code radius} is not a rigid square radius. Each structure may alter
diff --git a/src/main/java/org/bukkit/attribute/AttributeModifier.java b/src/main/java/org/bukkit/attribute/AttributeModifier.java
index 0000000000000000000000000000000000000000..0000000000000000000000000000000000000000 100644
--- a/src/main/java/org/bukkit/attribute/AttributeModifier.java
+++ b/src/main/java/org/bukkit/attribute/AttributeModifier.java
@@ -0,0 +0,0 @@ public class AttributeModifier implements ConfigurationSerializable, Keyed {
     }
 
     /**
-     * Get the {@link EquipmentSlot} this AttributeModifier is active on,
-     * or null if this modifier is applicable for any slot.
+     * Get the {@link EquipmentSlotGroup} this AttributeModifier is active on.
      *
      * @return the slot
      */
diff --git a/src/main/java/org/bukkit/block/Bed.java b/src/main/java/org/bukkit/block/Bed.java
index 0000000000000000000000000000000000000000..0000000000000000000000000000000000000000 100644
--- a/src/main/java/org/bukkit/block/Bed.java
+++ b/src/main/java/org/bukkit/block/Bed.java
@@ -0,0 +0,0 @@ import org.bukkit.material.Colorable;
 
 /**
  * Represents a captured state of a bed.
- * @deprecated does not provide useful information beyond the material itself
  */
-@Deprecated
-public interface Bed extends TileState, Colorable { }
+// Paper start
+// @Deprecated
+public interface Bed extends TileState, Colorable {
+
+    @Override
+    @org.jetbrains.annotations.NotNull org.bukkit.DyeColor getColor();
+
+    /**
+     * <b>Unsupported</b>
+     *
+     * @throws UnsupportedOperationException not supported, set the block type
+     */
+    @Override
+    @org.jetbrains.annotations.Contract("_ -> fail")
+    @Deprecated(forRemoval = true)
+    void setColor(@org.bukkit.UndefinedNullability("not supported") org.bukkit.DyeColor color);
+// Paper end
+}
diff --git a/src/main/java/org/bukkit/block/Block.java b/src/main/java/org/bukkit/block/Block.java
index 0000000000000000000000000000000000000000..0000000000000000000000000000000000000000 100644
--- a/src/main/java/org/bukkit/block/Block.java
+++ b/src/main/java/org/bukkit/block/Block.java
@@ -0,0 +0,0 @@ public interface Block extends Metadatable, Translatable {
      * Gets the temperature of this block.
      * <p>
      * If the raw biome temperature without adjusting for height effects is
-     * required then please use {@link World#getTemperature(int, int)}.
+     * required then please use {@link World#getTemperature(int, int, int)}.
      *
      * @return Temperature of this block
      */
@@ -0,0 +0,0 @@ public interface Block extends Metadatable, Translatable {
     boolean applyBoneMeal(@NotNull BlockFace face);
 
     /**
-     * Returns a list of items which would drop by destroying this block
+     * Returns a list of items which could drop by destroying this block.
+     * <p>
+     * The items are not guaranteed to be consistent across multiple calls to this
+     * method as this just uses the block type's loot table.
      *
      * @return a list of dropped items for this type of block
      */
@@ -0,0 +0,0 @@ public interface Block extends Metadatable, Translatable {
     Collection<ItemStack> getDrops();
 
     /**
-     * Returns a list of items which would drop by destroying this block with
-     * a specific tool
+     * Returns a list of items which could drop by destroying this block with
+     * a specific tool.
+     * <p>
+     * The items are not guaranteed to be consistent across multiple calls to this
+     * method as this just uses the block type's loot table.
      *
      * @param tool The tool or item in hand used for digging
      * @return a list of dropped items for this type of block
@@ -0,0 +0,0 @@ public interface Block extends Metadatable, Translatable {
     Collection<ItemStack> getDrops(@Nullable ItemStack tool);
 
     /**
-     * Returns a list of items which would drop by the entity destroying this
-     * block with a specific tool
+     * Returns a list of items which could drop by the entity destroying this
+     * block with a specific tool.
+     * <p>
+     * The items are not guaranteed to be consistent across multiple calls to this
+     * method as this just uses the block type's loot table.
      *
      * @param tool The tool or item in hand used for digging
      * @param entity the entity destroying the block
diff --git a/src/main/java/org/bukkit/block/data/BlockData.java b/src/main/java/org/bukkit/block/data/BlockData.java
index 0000000000000000000000000000000000000000..0000000000000000000000000000000000000000 100644
--- a/src/main/java/org/bukkit/block/data/BlockData.java
+++ b/src/main/java/org/bukkit/block/data/BlockData.java
@@ -0,0 +0,0 @@ public interface BlockData extends Cloneable {
      * {@link Material#REDSTONE_WIRE} -> {@link Material#REDSTONE}
      * {@link Material#CARROTS} -> {@link Material#CARROT}
      * </pre>
-     * @return placement material
+     * @return placement material or {@link Material#AIR} if it doesn't have one
      */
     @NotNull
     Material getPlacementMaterial();
diff --git a/src/main/java/org/bukkit/block/data/FaceAttachable.java b/src/main/java/org/bukkit/block/data/FaceAttachable.java
index 0000000000000000000000000000000000000000..0000000000000000000000000000000000000000 100644
--- a/src/main/java/org/bukkit/block/data/FaceAttachable.java
+++ b/src/main/java/org/bukkit/block/data/FaceAttachable.java
@@ -0,0 +0,0 @@ public interface FaceAttachable extends BlockData {
          */
         WALL,
         /**
-         * The switch is mounted to the ceiling and pointing dowanrds.
+         * The switch is mounted to the ceiling and pointing downwards.
          */
         CEILING;
     }
diff --git a/src/main/java/org/bukkit/block/data/type/CommandBlock.java b/src/main/java/org/bukkit/block/data/type/CommandBlock.java
index 0000000000000000000000000000000000000000..0000000000000000000000000000000000000000 100644
--- a/src/main/java/org/bukkit/block/data/type/CommandBlock.java
+++ b/src/main/java/org/bukkit/block/data/type/CommandBlock.java
@@ -0,0 +0,0 @@ import org.bukkit.block.data.Directional;
 
 /**
  * 'conditional' denotes whether this command block is conditional or not, i.e.
- * will only execute if the preceeding command block also executed successfully.
+ * will only execute if the preceding command block also executed successfully.
  */
 public interface CommandBlock extends Directional {
 
diff --git a/src/main/java/org/bukkit/block/data/type/Gate.java b/src/main/java/org/bukkit/block/data/type/Gate.java
index 0000000000000000000000000000000000000000..0000000000000000000000000000000000000000 100644
--- a/src/main/java/org/bukkit/block/data/type/Gate.java
+++ b/src/main/java/org/bukkit/block/data/type/Gate.java
@@ -0,0 +0,0 @@ import org.bukkit.block.data.Openable;
 import org.bukkit.block.data.Powerable;
 
 /**
- * 'in_wall" indicates if the fence gate is attached to a wall, and if true the
+ * 'in_wall' indicates if the fence gate is attached to a wall, and if true the
  * texture is lowered by a small amount to blend in better.
  */
 public interface Gate extends Directional, Openable, Powerable {
diff --git a/src/main/java/org/bukkit/block/data/type/Switch.java b/src/main/java/org/bukkit/block/data/type/Switch.java
index 0000000000000000000000000000000000000000..0000000000000000000000000000000000000000 100644
--- a/src/main/java/org/bukkit/block/data/type/Switch.java
+++ b/src/main/java/org/bukkit/block/data/type/Switch.java
@@ -0,0 +0,0 @@ public interface Switch extends Directional, FaceAttachable, Powerable {
      * Sets the value of the 'face' property.
      *
      * @param face the new 'face' value
-     * @deprecated use {@link #getAttachedFace()}
+     * @deprecated use {@link #setAttachedFace(AttachedFace)}
      */
     @Deprecated
     void setFace(@NotNull Face face);
@@ -0,0 +0,0 @@ public interface Switch extends Directional, FaceAttachable, Powerable {
          */
         WALL,
         /**
-         * The switch is mounted to the ceiling and pointing dowanrds.
+         * The switch is mounted to the ceiling and pointing downwards.
          */
         CEILING;
     }
diff --git a/src/main/java/org/bukkit/entity/ArmorStand.java b/src/main/java/org/bukkit/entity/ArmorStand.java
index 0000000000000000000000000000000000000000..0000000000000000000000000000000000000000 100644
--- a/src/main/java/org/bukkit/entity/ArmorStand.java
+++ b/src/main/java/org/bukkit/entity/ArmorStand.java
@@ -0,0 +0,0 @@ public interface ArmorStand extends LivingEntity {
      * @param move {@code true} if this armour stand can move, {@code false} otherwise
      */
     void setCanMove(boolean move);
+
+    @Override
+    org.bukkit.inventory.@NotNull EntityEquipment getEquipment();
     // Paper end
 }
diff --git a/src/main/java/org/bukkit/entity/Arrow.java b/src/main/java/org/bukkit/entity/Arrow.java
index 0000000000000000000000000000000000000000..0000000000000000000000000000000000000000 100644
--- a/src/main/java/org/bukkit/entity/Arrow.java
+++ b/src/main/java/org/bukkit/entity/Arrow.java
@@ -0,0 +0,0 @@ public interface Arrow extends AbstractArrow {
      * Removes a custom potion effect from this arrow.
      *
      * @param type the potion effect type to remove
-     * @return true if the an effect was removed as a result of this call
+     * @return true if the effect was removed as a result of this call
      * @throws IllegalArgumentException if this operation would leave the Arrow
      * in a state with no Custom Effects and PotionType.UNCRAFTABLE
      */
diff --git a/src/main/java/org/bukkit/entity/EnderDragon.java b/src/main/java/org/bukkit/entity/EnderDragon.java
index 0000000000000000000000000000000000000000..0000000000000000000000000000000000000000 100644
--- a/src/main/java/org/bukkit/entity/EnderDragon.java
+++ b/src/main/java/org/bukkit/entity/EnderDragon.java
@@ -0,0 +0,0 @@ public interface EnderDragon extends ComplexLivingEntity, Boss, Mob, Enemy {
          */
         FLY_TO_PORTAL,
         /**
-         * The dragon will land on on the portal. If the dragon is not near
+         * The dragon will land on the portal. If the dragon is not near
          * the portal, it will fly to it before mounting.
          */
         LAND_ON_PORTAL,
diff --git a/src/main/java/org/bukkit/entity/Entity.java b/src/main/java/org/bukkit/entity/Entity.java
index 0000000000000000000000000000000000000000..0000000000000000000000000000000000000000 100644
--- a/src/main/java/org/bukkit/entity/Entity.java
+++ b/src/main/java/org/bukkit/entity/Entity.java
@@ -0,0 +0,0 @@ public interface Entity extends Metadatable, CommandSender, Nameable, Persistent
     public List<org.bukkit.entity.Entity> getNearbyEntities(double x, double y, double z);
 
     /**
-     * Returns a unique id for this entity
+     * Returns the network protocol ID for this entity. This is
+     * not to be used as an identifier for the entity except in
+     * network-related operations. Use {@link #getUniqueId()} as
+     * an entity identifier instead.
      *
-     * @return Entity id
+     * @return the network protocol ID
+     * @see #getUniqueId()
      */
     public int getEntityId();
 
diff --git a/src/main/java/org/bukkit/entity/HumanEntity.java b/src/main/java/org/bukkit/entity/HumanEntity.java
index 0000000000000000000000000000000000000000..0000000000000000000000000000000000000000 100644
--- a/src/main/java/org/bukkit/entity/HumanEntity.java
+++ b/src/main/java/org/bukkit/entity/HumanEntity.java
@@ -0,0 +0,0 @@ import org.jetbrains.annotations.Nullable;
  */
 public interface HumanEntity extends LivingEntity, AnimalTamer, InventoryHolder {
 
+    // Paper start
+    @Override
+    org.bukkit.inventory.@NotNull EntityEquipment getEquipment();
+    // Paper end
+
     /**
      * Returns the name of this player
      *
diff --git a/src/main/java/org/bukkit/entity/ItemFrame.java b/src/main/java/org/bukkit/entity/ItemFrame.java
index 0000000000000000000000000000000000000000..0000000000000000000000000000000000000000 100644
--- a/src/main/java/org/bukkit/entity/ItemFrame.java
+++ b/src/main/java/org/bukkit/entity/ItemFrame.java
@@ -0,0 +0,0 @@ public interface ItemFrame extends Hanging {
     public void setRotation(@NotNull Rotation rotation) throws IllegalArgumentException;
 
     /**
-     * Returns whether the item frame is be visible or not.
+     * Returns whether the item frame is visible or not.
      *
      * @return whether the item frame is visible or not
      */
diff --git a/src/main/java/org/bukkit/entity/Mob.java b/src/main/java/org/bukkit/entity/Mob.java
index 0000000000000000000000000000000000000000..0000000000000000000000000000000000000000 100644
--- a/src/main/java/org/bukkit/entity/Mob.java
+++ b/src/main/java/org/bukkit/entity/Mob.java
@@ -0,0 +0,0 @@ import org.jetbrains.annotations.Nullable;
  */
 public interface Mob extends LivingEntity, Lootable {
 
+    // Paper start
+    @Override
+    org.bukkit.inventory.@org.jetbrains.annotations.NotNull EntityEquipment getEquipment();
+    // Paper end
     /**
      * Instructs this Mob to set the specified LivingEntity as its target.
      * <p>
diff --git a/src/main/java/org/bukkit/entity/PigZombie.java b/src/main/java/org/bukkit/entity/PigZombie.java
index 0000000000000000000000000000000000000000..0000000000000000000000000000000000000000 100644
--- a/src/main/java/org/bukkit/entity/PigZombie.java
+++ b/src/main/java/org/bukkit/entity/PigZombie.java
@@ -0,0 +0,0 @@ public interface PigZombie extends Zombie {
 
     /**
      * <b>Not applicable to this entity</b>
-     *
-     * @return UnsuppotedOperationException
      */
     @Override
     public int getConversionTime();
diff --git a/src/main/java/org/bukkit/entity/Player.java b/src/main/java/org/bukkit/entity/Player.java
index 0000000000000000000000000000000000000000..0000000000000000000000000000000000000000 100644
--- a/src/main/java/org/bukkit/entity/Player.java
+++ b/src/main/java/org/bukkit/entity/Player.java
@@ -0,0 +0,0 @@ public interface Player extends HumanEntity, Conversable, OfflinePlayer, PluginM
 
     /**
      * Saves the players current location, health, inventory, motion, and
-     * other information into the username.dat file, in the world/player
-     * folder
+     * other information into the &lt;uuid&gt;.dat file, in the
+     * &lt;level-name&gt;/playerdata/ folder.
      */
     public void saveData();
 
     /**
      * Loads the players current location, health, inventory, motion, and
-     * other information from the username.dat file, in the world/player
-     * folder.
+     * other information from the &lt;uuid&gt;.dat file, in the
+     * &lt;level-name&gt;/playerdata/ folder.
      * <p>
      * Note: This will overwrite the players current inventory, health,
      * motion, etc, with the state from the saved dat file.
@@ -0,0 +0,0 @@ public interface Player extends HumanEntity, Conversable, OfflinePlayer, PluginM
     /**
      * Plays an effect to just this player.
      *
-     * @param <T> the data based based on the type of the effect
+     * @param <T> the data based on the type of the effect
      * @param loc the location to play the effect at
      * @param effect the {@link Effect}
      * @param data a data bit needed for some effects
@@ -0,0 +0,0 @@ public interface Player extends HumanEntity, Conversable, OfflinePlayer, PluginM
      *
      * Use supplied alternative character to the section symbol to represent legacy color codes.
      *
-     * @param alternateChar Alternate symbol such as '&'
+     * @param alternateChar Alternate symbol such as '&amp;'
      * @param message The message to send
      * @deprecated use {@link #sendActionBar(net.kyori.adventure.text.Component)}
      */
@@ -0,0 +0,0 @@ public interface Player extends HumanEntity, Conversable, OfflinePlayer, PluginM
 
     /**
      * Allows this player to see a player that was previously hidden. If
-     * another another plugin had hidden the player too, then the player will
+     * another plugin had hidden the player too, then the player will
      * remain hidden until the other plugin calls this method too.
      *
      * @param plugin Plugin that wants to show the player
@@ -0,0 +0,0 @@ public interface Player extends HumanEntity, Conversable, OfflinePlayer, PluginM
 
     /**
      * Allows this player to see an entity that was previously hidden. If
-     * another another plugin had hidden the entity too, then the entity will
+     * another plugin had hidden the entity too, then the entity will
      * remain hidden until the other plugin calls this method too.
      *
      * @param plugin Plugin that wants to show the entity
@@ -0,0 +0,0 @@ public interface Player extends HumanEntity, Conversable, OfflinePlayer, PluginM
      *     case this method will have no affect on them. Use the
      *     {@link PlayerResourcePackStatusEvent} to figure out whether or not
      *     the player loaded the pack!
-     * <li>There is no concept of resetting texture packs back to default
-     *     within Minecraft, so players will have to relog to do so or you
-     *     have to send an empty pack.
      * <li>The request is send with "null" as the hash. This might result
      *     in newer versions not loading the pack correctly.
      * </ul>
@@ -0,0 +0,0 @@ public interface Player extends HumanEntity, Conversable, OfflinePlayer, PluginM
      *     case this method will have no affect on them. Use the
      *     {@link PlayerResourcePackStatusEvent} to figure out whether or not
      *     the player loaded the pack!
-     * <li>There is no concept of resetting resource packs back to default
-     *     within Minecraft, so players will have to relog to do so or you
-     *     have to send an empty pack.
      * <li>The request is send with empty string as the hash. This might result
      *     in newer versions not loading the pack correctly.
      * </ul>
@@ -0,0 +0,0 @@ public interface Player extends HumanEntity, Conversable, OfflinePlayer, PluginM
      *     case this method will have no affect on them. Use the
      *     {@link PlayerResourcePackStatusEvent} to figure out whether or not
      *     the player loaded the pack!
-     * <li>There is no concept of resetting resource packs back to default
-     *     within Minecraft, so players will have to relog to do so or you
-     *     have to send an empty pack.
      * <li>The request is sent with empty string as the hash when the hash is
      *     not provided. This might result in newer versions not loading the
      *     pack correctly.
diff --git a/src/main/java/org/bukkit/entity/Slime.java b/src/main/java/org/bukkit/entity/Slime.java
index 0000000000000000000000000000000000000000..0000000000000000000000000000000000000000 100644
--- a/src/main/java/org/bukkit/entity/Slime.java
+++ b/src/main/java/org/bukkit/entity/Slime.java
@@ -0,0 +0,0 @@ public interface Slime extends Mob, Enemy {
     public int getSize();
 
     /**
+     * Setting the size of the slime (regardless of previous size)
+     * will set the following attributes:
+     * <ul>
+     *     <li>{@link org.bukkit.attribute.Attribute#GENERIC_MAX_HEALTH}</li>
+     *     <li>{@link org.bukkit.attribute.Attribute#GENERIC_MOVEMENT_SPEED}</li>
+     *     <li>{@link org.bukkit.attribute.Attribute#GENERIC_ATTACK_DAMAGE}</li>
+     * </ul>
+     * to their per-size defaults and heal the
+     * slime to its max health (assuming it's alive).
+     *
      * @param sz The new size of the slime.
      */
     public void setSize(int sz);
diff --git a/src/main/java/org/bukkit/entity/Sniffer.java b/src/main/java/org/bukkit/entity/Sniffer.java
index 0000000000000000000000000000000000000000..0000000000000000000000000000000000000000 100644
--- a/src/main/java/org/bukkit/entity/Sniffer.java
+++ b/src/main/java/org/bukkit/entity/Sniffer.java
@@ -0,0 +0,0 @@ public interface Sniffer extends Animals {
 
     /**
      * Gets the locations explored by the sniffer.
-     * <br>
-     * <b>Note:</b> the returned locations use sniffer's current world.
      *
      * @return a collection of locations
      */
@@ -0,0 +0,0 @@ public interface Sniffer extends Animals {
 
     /**
      * Remove a location of the explored locations.
-     * <br>
-     * <b>Note:</b> the location must be in the sniffer's current world for this
-     * method to have any effect.
      *
      * @param location the location to remove
      * @see #getExploredLocations()
diff --git a/src/main/java/org/bukkit/entity/Villager.java b/src/main/java/org/bukkit/entity/Villager.java
index 0000000000000000000000000000000000000000..0000000000000000000000000000000000000000 100644
--- a/src/main/java/org/bukkit/entity/Villager.java
+++ b/src/main/java/org/bukkit/entity/Villager.java
@@ -0,0 +0,0 @@ public interface Villager extends AbstractVillager {
          */
         Profession NITWIT = getProfession("nitwit");
         /**
-         * Sheperd profession. Wears a brown robe. Shepherds primarily trade for
+         * Shepherd profession. Wears a brown robe. Shepherds primarily trade for
          * wool items, and shears.
          */
         Profession SHEPHERD = getProfession("shepherd");
diff --git a/src/main/java/org/bukkit/event/block/BlockDropItemEvent.java b/src/main/java/org/bukkit/event/block/BlockDropItemEvent.java
index 0000000000000000000000000000000000000000..0000000000000000000000000000000000000000 100644
--- a/src/main/java/org/bukkit/event/block/BlockDropItemEvent.java
+++ b/src/main/java/org/bukkit/event/block/BlockDropItemEvent.java
@@ -0,0 +0,0 @@ import org.bukkit.event.HandlerList;
 import org.jetbrains.annotations.NotNull;
 
 /**
- * Called if a block broken by a player drops an item.
+ * Called after a block is broken by a player and potential drops are computed, even if said blocks loot table
+ * does not define any drops at the point the event is constructed.
  *
  * If the block break is cancelled, this event won't be called.
  *
- * If isDropItems in BlockBreakEvent is set to false, this event won't be
+ * If isDropItems in {@link org.bukkit.event.block.BlockBreakEvent} is set to false, this event won't be
  * called.
  *
+ * If a block is broken and isDropItems is set to true, this event will be called even if the block does
+ * not drop any items, for example glass broken by hand. In this case, #getItems() will be empty.
+ *
  * This event will also be called if the player breaks a multi block structure,
- * for example a torch on top of a stone. Both items will have an event call.
+ * for example a torch on top of a stone. Both items will be included in the #getItems() list.
  *
  * The Block is already broken as this event is called, so #getBlock() will be
  * AIR in most cases. Use #getBlockState() for more Information about the broken
diff --git a/src/main/java/org/bukkit/event/block/BlockExplodeEvent.java b/src/main/java/org/bukkit/event/block/BlockExplodeEvent.java
index 0000000000000000000000000000000000000000..0000000000000000000000000000000000000000 100644
--- a/src/main/java/org/bukkit/event/block/BlockExplodeEvent.java
+++ b/src/main/java/org/bukkit/event/block/BlockExplodeEvent.java
@@ -0,0 +0,0 @@ import org.jetbrains.annotations.NotNull;
  * Note that due to the nature of explosions, {@link #getBlock()} will always be
  * an air block. {@link #getExplodedBlockState()} should be used to get
  * information about the block state that exploded.
+ * <p>
+ * The event isn't called if the {@link org.bukkit.GameRule#MOB_GRIEFING}
+ * is disabled as no block interaction will occur.
  */
 public class BlockExplodeEvent extends BlockEvent implements Cancellable {
     private static final HandlerList handlers = new HandlerList();
diff --git a/src/main/java/org/bukkit/event/block/BlockPistonRetractEvent.java b/src/main/java/org/bukkit/event/block/BlockPistonRetractEvent.java
index 0000000000000000000000000000000000000000..0000000000000000000000000000000000000000 100644
--- a/src/main/java/org/bukkit/event/block/BlockPistonRetractEvent.java
+++ b/src/main/java/org/bukkit/event/block/BlockPistonRetractEvent.java
@@ -0,0 +0,0 @@ public class BlockPistonRetractEvent extends BlockPistonEvent {
 
     /**
      * Get an immutable list of the blocks which will be moved by the
-     * extending.
+     * retracting.
      *
      * @return Immutable list of the moved blocks.
      */
diff --git a/src/main/java/org/bukkit/event/block/BlockPlaceEvent.java b/src/main/java/org/bukkit/event/block/BlockPlaceEvent.java
index 0000000000000000000000000000000000000000..0000000000000000000000000000000000000000 100644
--- a/src/main/java/org/bukkit/event/block/BlockPlaceEvent.java
+++ b/src/main/java/org/bukkit/event/block/BlockPlaceEvent.java
@@ -0,0 +0,0 @@ public class BlockPlaceEvent extends BlockEvent implements Cancellable {
 
     /**
      * Gets the value whether the player would be allowed to build here.
-     * Defaults to spawn if the server was going to stop them (such as, the
+     * Defaults to false if the server was going to stop them (such as, the
      * player is in Spawn). Note that this is an entirely different check
      * than BLOCK_CANBUILD, as this refers to a player, not universe-physics
      * rule like cactus on dirt.
diff --git a/src/main/java/org/bukkit/event/enchantment/PrepareItemEnchantEvent.java b/src/main/java/org/bukkit/event/enchantment/PrepareItemEnchantEvent.java
index 0000000000000000000000000000000000000000..0000000000000000000000000000000000000000 100644
--- a/src/main/java/org/bukkit/event/enchantment/PrepareItemEnchantEvent.java
+++ b/src/main/java/org/bukkit/event/enchantment/PrepareItemEnchantEvent.java
@@ -0,0 +0,0 @@ public class PrepareItemEnchantEvent extends InventoryEvent implements Cancellab
     /**
      * Get a list of available {@link EnchantmentOffer} for the player. You can
      * modify the values to change the available offers for the player. An offer
-     * may be null, if there isn't a enchantment offer at a specific slot. There
+     * may be null, if there isn't an enchantment offer at a specific slot. There
      * are 3 slots in the enchantment table available to modify.
      *
      * @return list of available enchantment offers
diff --git a/src/main/java/org/bukkit/event/entity/AreaEffectCloudApplyEvent.java b/src/main/java/org/bukkit/event/entity/AreaEffectCloudApplyEvent.java
index 0000000000000000000000000000000000000000..0000000000000000000000000000000000000000 100644
--- a/src/main/java/org/bukkit/event/entity/AreaEffectCloudApplyEvent.java
+++ b/src/main/java/org/bukkit/event/entity/AreaEffectCloudApplyEvent.java
@@ -0,0 +0,0 @@ import org.bukkit.event.HandlerList;
 import org.jetbrains.annotations.NotNull;
 
 /**
- * Called when a lingering potion applies it's effects. Happens
+ * Called when a lingering potion applies its effects. Happens
  * once every 5 ticks
  */
 public class AreaEffectCloudApplyEvent extends EntityEvent implements Cancellable {
diff --git a/src/main/java/org/bukkit/event/entity/CreatureSpawnEvent.java b/src/main/java/org/bukkit/event/entity/CreatureSpawnEvent.java
index 0000000000000000000000000000000000000000..0000000000000000000000000000000000000000 100644
--- a/src/main/java/org/bukkit/event/entity/CreatureSpawnEvent.java
+++ b/src/main/java/org/bukkit/event/entity/CreatureSpawnEvent.java
@@ -0,0 +0,0 @@ public class CreatureSpawnEvent extends EntitySpawnEvent {
          */
         DROWNED,
         /**
-         * When an cow is spawned by shearing a mushroom cow
+         * When a cow is spawned by shearing a mushroom cow
          */
         SHEARED,
         /**
-         * When eg an effect cloud is spawned as a result of a creeper exploding
+         * When an entity is spawned as a result of an explosion. Like an area effect cloud from
+         * a creeper or a dragon fireball.
          */
         EXPLOSION,
         /**
diff --git a/src/main/java/org/bukkit/event/entity/EntityDamageByBlockEvent.java b/src/main/java/org/bukkit/event/entity/EntityDamageByBlockEvent.java
index 0000000000000000000000000000000000000000..0000000000000000000000000000000000000000 100644
--- a/src/main/java/org/bukkit/event/entity/EntityDamageByBlockEvent.java
+++ b/src/main/java/org/bukkit/event/entity/EntityDamageByBlockEvent.java
@@ -0,0 +0,0 @@ import org.jetbrains.annotations.Nullable;
 
 /**
  * Called when an entity is damaged by a block
+ * <p>
+ * For explosions, the Block returned by {@link #getDamager()} has
+ * already been cleared. See {@link #getDamagerBlockState()} for a snapshot
+ * of the block if it has already been changed.
  */
 public class EntityDamageByBlockEvent extends EntityDamageEvent {
     private final Block damager;
@@ -0,0 +0,0 @@ public class EntityDamageByBlockEvent extends EntityDamageEvent {
 
     /**
      * Returns the captured BlockState of the block that damaged the player.
+     * <p>
+     * This block state is not placed so {@link org.bukkit.block.BlockState#isPlaced}
+     * will be false.
      *
      * @return the block state
      */
diff --git a/src/main/java/org/bukkit/event/entity/EntityExplodeEvent.java b/src/main/java/org/bukkit/event/entity/EntityExplodeEvent.java
index 0000000000000000000000000000000000000000..0000000000000000000000000000000000000000 100644
--- a/src/main/java/org/bukkit/event/entity/EntityExplodeEvent.java
+++ b/src/main/java/org/bukkit/event/entity/EntityExplodeEvent.java
@@ -0,0 +0,0 @@ import org.bukkit.event.HandlerList;
 import org.jetbrains.annotations.NotNull;
 
 /**
- * Called when an entity explodes
+ * Called when an entity explodes interacting with blocks. The
+ * event isn't called if the {@link org.bukkit.GameRule#MOB_GRIEFING}
+ * is disabled as no block interaction will occur.
  */
 public class EntityExplodeEvent extends EntityEvent implements Cancellable {
     private static final HandlerList handlers = new HandlerList();
diff --git a/src/main/java/org/bukkit/event/entity/EntityPickupItemEvent.java b/src/main/java/org/bukkit/event/entity/EntityPickupItemEvent.java
index 0000000000000000000000000000000000000000..0000000000000000000000000000000000000000 100644
--- a/src/main/java/org/bukkit/event/entity/EntityPickupItemEvent.java
+++ b/src/main/java/org/bukkit/event/entity/EntityPickupItemEvent.java
@@ -0,0 +0,0 @@ import org.bukkit.event.HandlerList;
 import org.jetbrains.annotations.NotNull;
 
 /**
- * Thrown when a entity picks an item up from the ground
+ * Thrown when an entity picks an item up from the ground
  */
 public class EntityPickupItemEvent extends EntityEvent implements Cancellable {
     private static final HandlerList handlers = new HandlerList();
diff --git a/src/main/java/org/bukkit/event/entity/EntityPlaceEvent.java b/src/main/java/org/bukkit/event/entity/EntityPlaceEvent.java
index 0000000000000000000000000000000000000000..0000000000000000000000000000000000000000 100644
--- a/src/main/java/org/bukkit/event/entity/EntityPlaceEvent.java
+++ b/src/main/java/org/bukkit/event/entity/EntityPlaceEvent.java
@@ -0,0 +0,0 @@ import org.jetbrains.annotations.NotNull;
 import org.jetbrains.annotations.Nullable;
 
 /**
- * Triggered when a entity is created in the world by a player "placing" an item
+ * Triggered when an entity is created in the world by a player "placing" an item
  * on a block.
  * <br>
  * Note that this event is currently only fired for four specific placements:
diff --git a/src/main/java/org/bukkit/event/entity/EntityPotionEffectEvent.java b/src/main/java/org/bukkit/event/entity/EntityPotionEffectEvent.java
index 0000000000000000000000000000000000000000..0000000000000000000000000000000000000000 100644
--- a/src/main/java/org/bukkit/event/entity/EntityPotionEffectEvent.java
+++ b/src/main/java/org/bukkit/event/entity/EntityPotionEffectEvent.java
@@ -0,0 +0,0 @@ public class EntityPotionEffectEvent extends EntityEvent implements Cancellable
     public enum Action {
 
         /**
-         * When the potion effect is added because the entity didn't have it's
+         * When the potion effect is added because the entity didn't have its
          * type.
          */
         ADDED,
@@ -0,0 +0,0 @@ public class EntityPotionEffectEvent extends EntityEvent implements Cancellable
          */
         SPIDER_SPAWN,
         /**
-         * When the entity gets effects from a totem item saving it's life.
+         * When the entity gets effects from a totem item saving its life.
          */
         TOTEM,
         /**
diff --git a/src/main/java/org/bukkit/event/entity/EntityRegainHealthEvent.java b/src/main/java/org/bukkit/event/entity/EntityRegainHealthEvent.java
index 0000000000000000000000000000000000000000..0000000000000000000000000000000000000000 100644
--- a/src/main/java/org/bukkit/event/entity/EntityRegainHealthEvent.java
+++ b/src/main/java/org/bukkit/event/entity/EntityRegainHealthEvent.java
@@ -0,0 +0,0 @@ public class EntityRegainHealthEvent extends EntityEvent implements Cancellable
          */
         SATIATED,
         /**
-         * When a player regains health from eating consumables
+         * When an animal regains health from eating consumables
          */
         EATING,
         /**
diff --git a/src/main/java/org/bukkit/event/entity/EntityTargetEvent.java b/src/main/java/org/bukkit/event/entity/EntityTargetEvent.java
index 0000000000000000000000000000000000000000..0000000000000000000000000000000000000000 100644
--- a/src/main/java/org/bukkit/event/entity/EntityTargetEvent.java
+++ b/src/main/java/org/bukkit/event/entity/EntityTargetEvent.java
@@ -0,0 +0,0 @@ public class EntityTargetEvent extends EntityEvent implements Cancellable {
         FOLLOW_LEADER,
         /**
          * When another entity tempts this entity by having a desired item such
-         * as wheat in it's hand.
+         * as wheat in its hand.
          */
         TEMPT,
         /**
diff --git a/src/main/java/org/bukkit/event/entity/PiglinBarterEvent.java b/src/main/java/org/bukkit/event/entity/PiglinBarterEvent.java
index 0000000000000000000000000000000000000000..0000000000000000000000000000000000000000 100644
--- a/src/main/java/org/bukkit/event/entity/PiglinBarterEvent.java
+++ b/src/main/java/org/bukkit/event/entity/PiglinBarterEvent.java
@@ -0,0 +0,0 @@ import org.jetbrains.annotations.NotNull;
 /**
  * Stores all data related to the bartering interaction with a piglin.
  *
- * This event can be triggered by a piglin picking up an item that's on its
- * bartering list.
+ * Called when a piglin completes a barter.
  */
 public class PiglinBarterEvent extends EntityEvent implements Cancellable {
 
diff --git a/src/main/java/org/bukkit/event/inventory/FurnaceBurnEvent.java b/src/main/java/org/bukkit/event/inventory/FurnaceBurnEvent.java
index 0000000000000000000000000000000000000000..0000000000000000000000000000000000000000 100644
--- a/src/main/java/org/bukkit/event/inventory/FurnaceBurnEvent.java
+++ b/src/main/java/org/bukkit/event/inventory/FurnaceBurnEvent.java
@@ -0,0 +0,0 @@ import org.bukkit.inventory.ItemStack;
 import org.jetbrains.annotations.NotNull;
 
 /**
- * Called when an ItemStack is successfully burned as fuel in a furnace.
+ * Called when an ItemStack is successfully burned as fuel in a furnace-like block such as a
+ * {@link org.bukkit.block.Furnace}, {@link org.bukkit.block.Smoker}, or
+ * {@link org.bukkit.block.BlastFurnace}.
  */
 public class FurnaceBurnEvent extends BlockEvent implements Cancellable {
     private static final HandlerList handlers = new HandlerList();
diff --git a/src/main/java/org/bukkit/event/inventory/FurnaceExtractEvent.java b/src/main/java/org/bukkit/event/inventory/FurnaceExtractEvent.java
index 0000000000000000000000000000000000000000..0000000000000000000000000000000000000000 100644
--- a/src/main/java/org/bukkit/event/inventory/FurnaceExtractEvent.java
+++ b/src/main/java/org/bukkit/event/inventory/FurnaceExtractEvent.java
@@ -0,0 +0,0 @@ import org.bukkit.material.MaterialData;
 import org.jetbrains.annotations.NotNull;
 
 /**
- * This event is called when a player takes items out of the furnace
+ * This event is called when a player takes items out of a furnace-like block such as a
+ * {@link org.bukkit.block.Furnace}, {@link org.bukkit.block.Smoker}, or
+ * {@link org.bukkit.block.BlastFurnace}.
  */
 public class FurnaceExtractEvent extends BlockExpEvent {
     private final Player player;
diff --git a/src/main/java/org/bukkit/event/inventory/FurnaceSmeltEvent.java b/src/main/java/org/bukkit/event/inventory/FurnaceSmeltEvent.java
index 0000000000000000000000000000000000000000..0000000000000000000000000000000000000000 100644
--- a/src/main/java/org/bukkit/event/inventory/FurnaceSmeltEvent.java
+++ b/src/main/java/org/bukkit/event/inventory/FurnaceSmeltEvent.java
@@ -0,0 +0,0 @@ import org.bukkit.inventory.ItemStack;
 import org.jetbrains.annotations.NotNull;
 
 /**
- * Called when an ItemStack is successfully smelted in a furnace.
+ * Called when an ItemStack is successfully smelted in a furnace-like block
+ * such as a {@link org.bukkit.block.Furnace}, {@link org.bukkit.block.Smoker},
+ * or {@link org.bukkit.block.BlastFurnace}.
  */
 public class FurnaceSmeltEvent extends BlockCookEvent {
 
diff --git a/src/main/java/org/bukkit/event/inventory/FurnaceStartSmeltEvent.java b/src/main/java/org/bukkit/event/inventory/FurnaceStartSmeltEvent.java
index 0000000000000000000000000000000000000000..0000000000000000000000000000000000000000 100644
--- a/src/main/java/org/bukkit/event/inventory/FurnaceStartSmeltEvent.java
+++ b/src/main/java/org/bukkit/event/inventory/FurnaceStartSmeltEvent.java
@@ -0,0 +0,0 @@ import org.bukkit.inventory.ItemStack;
 import org.jetbrains.annotations.NotNull;
 
 /**
- * Called when a Furnace starts smelting.
+ * Called when any of the furnace-like blocks start smelting.
+ * <p>
+ * Furnace-like blocks are {@link org.bukkit.block.Furnace},
+ * {@link org.bukkit.block.Smoker}, and {@link org.bukkit.block.BlastFurnace}.
  */
 public class FurnaceStartSmeltEvent extends InventoryBlockStartEvent {
     private static final HandlerList handlers = new HandlerList();
diff --git a/src/main/java/org/bukkit/event/inventory/InventoryClickEvent.java b/src/main/java/org/bukkit/event/inventory/InventoryClickEvent.java
index 0000000000000000000000000000000000000000..0000000000000000000000000000000000000000 100644
--- a/src/main/java/org/bukkit/event/inventory/InventoryClickEvent.java
+++ b/src/main/java/org/bukkit/event/inventory/InventoryClickEvent.java
@@ -0,0 +0,0 @@ import org.jetbrains.annotations.Nullable;
 /**
  * This event is called when a player clicks in an inventory.
  * <p>
+ * In case of a drag action within an inventory, InventoryClickEvent is never called.
+ * Instead, {@link InventoryDragEvent} is called at the end of the drag.
+ * <p>
  * Because InventoryClickEvent occurs within a modification of the Inventory,
  * not all Inventory related methods are safe to use.
  * <p>
- * The following should never be invoked by an EventHandler for
- * InventoryClickEvent using the HumanEntity or InventoryView associated with
- * this event:
+ * Methods that change the view a player is looking at should never be invoked
+ * by an EventHandler for InventoryClickEvent using the HumanEntity or
+ * InventoryView associated with this event.
+ * Examples of these include:
  * <ul>
  * <li>{@link HumanEntity#closeInventory()}
  * <li>{@link HumanEntity#openInventory(Inventory)}
@@ -0,0 +0,0 @@ public class InventoryClickEvent extends InventoryInteractEvent {
     /**
      * Gets the ItemStack currently in the clicked slot.
      *
-     * @return the item in the clicked
+     * @return the item in the clicked slot
      */
     @Nullable
     public ItemStack getCurrentItem() {
diff --git a/src/main/java/org/bukkit/event/inventory/InventoryCloseEvent.java b/src/main/java/org/bukkit/event/inventory/InventoryCloseEvent.java
index 0000000000000000000000000000000000000000..0000000000000000000000000000000000000000 100644
--- a/src/main/java/org/bukkit/event/inventory/InventoryCloseEvent.java
+++ b/src/main/java/org/bukkit/event/inventory/InventoryCloseEvent.java
@@ -0,0 +0,0 @@ import org.bukkit.inventory.InventoryView;
 import org.jetbrains.annotations.NotNull;
 
 /**
- * Represents a player related inventory event
+ * This event is called when a player closes an inventory.
+ * <p>
+ * Because InventoryCloseEvent occurs within a modification of the Inventory,
+ * not all Inventory related methods are safe to use.
+ * <p>
+ * Methods that change the view a player is looking at should never be invoked
+ * by an EventHandler for InventoryCloseEvent using the HumanEntity or
+ * InventoryView associated with this event.
+ * Examples of these include:
+ * <ul>
+ * <li>{@link HumanEntity#closeInventory()}
+ * <li>{@link HumanEntity#openInventory(org.bukkit.inventory.Inventory)}
+ * <li>{@link HumanEntity#openWorkbench(org.bukkit.Location, boolean)}
+ * <li>{@link HumanEntity#openEnchanting(org.bukkit.Location, boolean)}
+ * <li>{@link InventoryView#close()}
+ * </ul>
+ * To invoke one of these methods, schedule a task using
+ * {@link org.bukkit.scheduler.BukkitScheduler#runTask(org.bukkit.plugin.Plugin, Runnable)}, which will run the task
+ * on the next tick. Also be aware that this is not an exhaustive list, and
+ * other methods could potentially create issues as well.
  */
 public class InventoryCloseEvent extends InventoryEvent {
     private static final HandlerList handlers = new HandlerList();
diff --git a/src/main/java/org/bukkit/event/inventory/InventoryOpenEvent.java b/src/main/java/org/bukkit/event/inventory/InventoryOpenEvent.java
index 0000000000000000000000000000000000000000..0000000000000000000000000000000000000000 100644
--- a/src/main/java/org/bukkit/event/inventory/InventoryOpenEvent.java
+++ b/src/main/java/org/bukkit/event/inventory/InventoryOpenEvent.java
@@ -0,0 +0,0 @@ import org.bukkit.inventory.InventoryView;
 import org.jetbrains.annotations.NotNull;
 
 /**
- * Represents a player related inventory event
+ * Called when a player opens an inventory
  */
 public class InventoryOpenEvent extends InventoryEvent implements Cancellable {
     private static final HandlerList handlers = new HandlerList();
diff --git a/src/main/java/org/bukkit/event/inventory/PrepareAnvilEvent.java b/src/main/java/org/bukkit/event/inventory/PrepareAnvilEvent.java
index 0000000000000000000000000000000000000000..0000000000000000000000000000000000000000 100644
--- a/src/main/java/org/bukkit/event/inventory/PrepareAnvilEvent.java
+++ b/src/main/java/org/bukkit/event/inventory/PrepareAnvilEvent.java
@@ -0,0 +0,0 @@ public class PrepareAnvilEvent extends PrepareInventoryResultEvent {
         return (AnvilInventory) super.getInventory();
     }
 
+    /**
+     * {@inheritDoc}
+     *
+     * <p>
+     * Note: by default custom recipes in anvil are disabled
+     * you should define a repair cost on the anvil inventory
+     * greater or equals to zero in order to allow that.
+     *
+     * @param result result item
+     */
+    public void setResult(@Nullable ItemStack result) {
+        super.setResult(result);
+    }
+
     @NotNull
     @Override
     public AnvilView getView() {
diff --git a/src/main/java/org/bukkit/event/player/PlayerResourcePackStatusEvent.java b/src/main/java/org/bukkit/event/player/PlayerResourcePackStatusEvent.java
index 0000000000000000000000000000000000000000..0000000000000000000000000000000000000000 100644
--- a/src/main/java/org/bukkit/event/player/PlayerResourcePackStatusEvent.java
+++ b/src/main/java/org/bukkit/event/player/PlayerResourcePackStatusEvent.java
@@ -0,0 +0,0 @@ import org.bukkit.event.HandlerList;
 import org.jetbrains.annotations.NotNull;
 
 /**
- * Called when a player takes action on a resource pack request sent via
- * {@link Player#setResourcePack(java.lang.String)}.
+ * Called when a player takes action on a resource pack request.
+ * @see Player#setResourcePack(String, String)
+ * @see Player#setResourcePack(String, String, boolean)
  */
 public class PlayerResourcePackStatusEvent extends PlayerEvent {
 
diff --git a/src/main/java/org/bukkit/generator/ChunkGenerator.java b/src/main/java/org/bukkit/generator/ChunkGenerator.java
index 0000000000000000000000000000000000000000..0000000000000000000000000000000000000000 100644
--- a/src/main/java/org/bukkit/generator/ChunkGenerator.java
+++ b/src/main/java/org/bukkit/generator/ChunkGenerator.java
@@ -0,0 +0,0 @@ public abstract class ChunkGenerator {
          * Get the biome at x, y, z within chunk being generated
          *
          * @param x the x location in the chunk from 0-15 inclusive
-         * @param y the y location in the chunk from minimum (inclusive) -
+         * @param y the y location in the chunk from minHeight (inclusive) -
          * maxHeight (exclusive)
          * @param z the z location in the chunk from 0-15 inclusive
          * @return Biome value
diff --git a/src/main/java/org/bukkit/inventory/EntityEquipment.java b/src/main/java/org/bukkit/inventory/EntityEquipment.java
index 0000000000000000000000000000000000000000..0000000000000000000000000000000000000000 100644
--- a/src/main/java/org/bukkit/inventory/EntityEquipment.java
+++ b/src/main/java/org/bukkit/inventory/EntityEquipment.java
@@ -0,0 +0,0 @@ public interface EntityEquipment {
     public ItemStack getItem(@NotNull EquipmentSlot slot);
 
     /**
-     * Gets a copy of the item the entity is currently holding
+     * Gets the item the entity is currently holding
      * in their main hand.
      *
+     * <p>
+     * This returns a copy if this equipment instance is from a non-player,
+     * or it's an empty stack (has AIR as its type).
+     * For non-empty stacks from players, this returns a live mirror. You can check if this
+     * will return a mirror with
+     * <pre>{@code
+     * EntityEquipment equipment = entity.getEquipment();
+     * if (equipment instanceof PlayerInventory) {
+     *     equipment.getItemInMainHand(); // will return a mirror
+     * } else {
+     *     equipment.getItemInMainHand(); // will return a copy
+     * }
+     * }</pre>
+     *
      * @return the currently held item
      */
     @NotNull
@@ -0,0 +0,0 @@ public interface EntityEquipment {
     void setItemInMainHand(@Nullable ItemStack item, boolean silent);
 
     /**
-     * Gets a copy of the item the entity is currently holding
+     * Gets the item the entity is currently holding
      * in their off hand.
      *
+     * <p>
+     * This returns a copy if this equipment instance is from a non-player,
+     * or it's an empty stack (has AIR as its type).
+     * For non-empty stacks from players, this returns a live mirror. You can check if this
+     * will return a mirror with
+     * <pre>{@code
+     * EntityEquipment equipment = entity.getEquipment();
+     * if (equipment instanceof PlayerInventory) {
+     *     equipment.getItemInOffHand(); // will return a mirror
+     * } else {
+     *     equipment.getItemInOffHand(); // will return a copy
+     * }
+     * }</pre>
+     *
      * @return the currently held item
      */
     @NotNull
@@ -0,0 +0,0 @@ public interface EntityEquipment {
     void setItemInOffHand(@Nullable ItemStack item, boolean silent);
 
     /**
-     * Gets a copy of the item the entity is currently holding
+     * Gets the item the entity is currently holding
+     *
+     * <p>
+     * This returns a copy if this equipment instance is from a non-player,
+     * or it's an empty stack (has AIR as its type).
+     * For non-empty stacks from players, this returns a live mirror. You can check if this
+     * will return a mirror with
+     * <pre>{@code
+     * EntityEquipment equipment = entity.getEquipment();
+     * if (equipment instanceof PlayerInventory) {
+     *     equipment.getItemInHand(); // will return a mirror
+     * } else {
+     *     equipment.getItemInHand(); // will return a copy
+     * }
+     * }</pre>
      *
      * @return the currently held item
      * @see #getItemInMainHand()
@@ -0,0 +0,0 @@ public interface EntityEquipment {
     void setItemInHand(@Nullable ItemStack stack);
 
     /**
-     * Gets a copy of the helmet currently being worn by the entity
+     * Gets the helmet currently being worn by the entity
+     *
+     * <p>
+     * This returns a copy if this equipment instance is from a non-player.
+     * For stacks from players, this returns a live mirror (or null). You can check if this
+     * will return a mirror with
+     * <pre>{@code
+     * EntityEquipment equipment = entity.getEquipment();
+     * if (equipment instanceof PlayerInventory) {
+     *     equipment.getHelmet(); // will return a mirror
+     * } else {
+     *     equipment.getHelmet(); // will return a copy
+     * }
+     * }</pre>
      *
      * @return The helmet being worn
      */
-    @Nullable
+    @org.bukkit.UndefinedNullability("not null for entities, nullable for players") // Paper
     ItemStack getHelmet();
 
     /**
@@ -0,0 +0,0 @@ public interface EntityEquipment {
     void setHelmet(@Nullable ItemStack helmet, boolean silent);
 
     /**
-     * Gets a copy of the chest plate currently being worn by the entity
+     * Gets the chest plate currently being worn by the entity
+     *
+     * <p>
+     * This returns a copy if this equipment instance is from a non-player.
+     * For stacks from players, this returns a live mirror (or null). You can check if this
+     * will return a mirror with
+     * <pre>{@code
+     * EntityEquipment equipment = entity.getEquipment();
+     * if (equipment instanceof PlayerInventory) {
+     *     equipment.getChestplate(); // will return a mirror
+     * } else {
+     *     equipment.getChestplate(); // will return a copy
+     * }
+     * }</pre>
      *
      * @return The chest plate being worn
      */
-    @Nullable
+    @org.bukkit.UndefinedNullability("not null for entities, nullable for players") // Paper
     ItemStack getChestplate();
 
     /**
@@ -0,0 +0,0 @@ public interface EntityEquipment {
     void setChestplate(@Nullable ItemStack chestplate, boolean silent);
 
     /**
-     * Gets a copy of the leggings currently being worn by the entity
+     * Gets the leggings currently being worn by the entity
+     *
+     * <p>
+     * This returns a copy if this equipment instance is from a non-player.
+     * For stacks from players, this returns a live mirror (or null). You can check if this
+     * will return a mirror with
+     * <pre>{@code
+     * EntityEquipment equipment = entity.getEquipment();
+     * if (equipment instanceof PlayerInventory) {
+     *     equipment.getLeggings(); // will return a mirror
+     * } else {
+     *     equipment.getLeggings(); // will return a copy
+     * }
+     * }</pre>
      *
      * @return The leggings being worn
      */
-    @Nullable
+    @org.bukkit.UndefinedNullability("not null for entities, nullable for players") // Paper
     ItemStack getLeggings();
 
     /**
@@ -0,0 +0,0 @@ public interface EntityEquipment {
     void setLeggings(@Nullable ItemStack leggings, boolean silent);
 
     /**
-     * Gets a copy of the boots currently being worn by the entity
+     * Gets the boots currently being worn by the entity
+     *
+     * <p>
+     * This returns a copy if this equipment instance is from a non-player.
+     * For stacks from players, this returns a live mirror (or null). You can check if this
+     * will return a mirror with
+     * <pre>{@code
+     * EntityEquipment equipment = entity.getEquipment();
+     * if (equipment instanceof PlayerInventory) {
+     *     equipment.getBoots(); // will return a mirror
+     * } else {
+     *     equipment.getBoots(); // will return a copy
+     * }
+     * }</pre>
      *
      * @return The boots being worn
      */
-    @Nullable
+    @org.bukkit.UndefinedNullability("not null for entities, nullable for players") // Paper
     ItemStack getBoots();
 
     /**
@@ -0,0 +0,0 @@ public interface EntityEquipment {
     /**
      * Gets all ItemStacks from the armor slots.
      *
+     * <p>
+     * This returns a copy if this equipment instance is from a non-player,
+     * or it's an empty stack (has AIR as its type).
+     * For non-empty stacks from players, this returns a live mirror. You can check if this
+     * will return a mirror with
+     * <pre>{@code
+     * EntityEquipment equipment = entity.getEquipment();
+     * if (equipment instanceof PlayerInventory) {
+     *     equipment.getArmorContents(); // will return an array of mirror
+     * } else {
+     *     equipment.getArmorContents(); // will return an array of copies
+     * }
+     * }</pre>
+     *
      * @return all the ItemStacks from the armor slots. Individual items can be
      * null and are returned in a fixed order starting from the boots and going
      * up to the helmet
      */
-    @NotNull
-    ItemStack[] getArmorContents();
+    @org.bukkit.UndefinedNullability("not null elements for entities, nullable elements for players") ItemStack @NotNull [] getArmorContents(); // Paper
 
     /**
      * Sets the entities armor to the provided array of ItemStacks
@@ -0,0 +0,0 @@ public interface EntityEquipment {
      *
      * <ul>
      * <li>A drop chance of 0.0F will never drop
-     * <li>A drop chance of 1.0F will always drop
+     * <li>A drop chance of exactly 1.0F will always drop if killed by a player
+     * <li>A drop chance of greater than 1.0F will always drop killed by anything
      * </ul>
      *
      * @return chance of the currently held item being dropped (1 for non-{@link Mob})
@@ -0,0 +0,0 @@ public interface EntityEquipment {
      *
      * <ul>
      * <li>A drop chance of 0.0F will never drop
-     * <li>A drop chance of 1.0F will always drop
+     * <li>A drop chance of exactly 1.0F will always drop if killed by a player
+     * <li>A drop chance of greater than 1.0F will always drop if killed by anything
      * </ul>
      *
      * @param chance the chance of the main hand item being dropped
@@ -0,0 +0,0 @@ public interface EntityEquipment {
      *
      * <ul>
      * <li>A drop chance of 0.0F will never drop
-     * <li>A drop chance of 1.0F will always drop
+     * <li>A drop chance of exactly 1.0F will always drop if killed by a player
+     * <li>A drop chance of greater than 1.0F will always drop if killed by anything
      * </ul>
      *
      * @return chance of the off hand item being dropped (1 for non-{@link Mob})
@@ -0,0 +0,0 @@ public interface EntityEquipment {
      *
      * <ul>
      * <li>A drop chance of 0.0F will never drop
-     * <li>A drop chance of 1.0F will always drop
+     * <li>A drop chance of exactly 1.0F will always drop if killed by a player
+     * <li>A drop chance of greater than 1.0F will always drop if killed by anything
      * </ul>
      *
      * @param chance the chance of off hand item being dropped
@@ -0,0 +0,0 @@ public interface EntityEquipment {
      *
      * <ul>
      * <li>A drop chance of 0.0F will never drop
-     * <li>A drop chance of 1.0F will always drop
+     * <li>A drop chance of exactly 1.0F will always drop if killed by a player
+     * <li>A drop chance of greater than 1.0F will always drop if killed by anything
      * </ul>
      *
      * @return the chance of the helmet being dropped (1 for non-{@link Mob})
@@ -0,0 +0,0 @@ public interface EntityEquipment {
      *
      * <ul>
      * <li>A drop chance of 0.0F will never drop
-     * <li>A drop chance of 1.0F will always drop
+     * <li>A drop chance of exactly 1.0F will always drop if killed by a player
+     * <li>A drop chance of greater than 1.0F will always drop if killed by anything
      * </ul>
      *
      * @param chance of the helmet being dropped
@@ -0,0 +0,0 @@ public interface EntityEquipment {
      *
      * <ul>
      * <li>A drop chance of 0.0F will never drop
-     * <li>A drop chance of 1.0F will always drop
+     * <li>A drop chance of exactly 1.0F will always drop if killed by a player
+     * <li>A drop chance of greater than 1.0F will always drop if killed by anything
      * </ul>
      *
      * @return the chance of the chest plate being dropped (1 for non-{@link Mob})
@@ -0,0 +0,0 @@ public interface EntityEquipment {
      *
      * <ul>
      * <li>A drop chance of 0.0F will never drop
-     * <li>A drop chance of 1.0F will always drop
+     * <li>A drop chance of exactly 1.0F will always drop if killed by a player
+     * <li>A drop chance of greater than 1.0F will always drop if killed by anything
      * </ul>
      *
      * @param chance of the chest plate being dropped
@@ -0,0 +0,0 @@ public interface EntityEquipment {
      *
      * <ul>
      * <li>A drop chance of 0.0F will never drop
-     * <li>A drop chance of 1.0F will always drop
+     * <li>A drop chance of exactly 1.0F will always drop if killed by a player
+     * <li>A drop chance of greater than 1.0F will always drop if killed by anything
      * </ul>
      *
      * @return the chance of the leggings being dropped (1 for non-{@link Mob})
@@ -0,0 +0,0 @@ public interface EntityEquipment {
      *
      * <ul>
      * <li>A drop chance of 0.0F will never drop
-     * <li>A drop chance of 1.0F will always drop
+     * <li>A drop chance of exactly 1.0F will always drop if killed by a player
+     * <li>A drop chance of greater than 1.0F will always drop if killed by anything
      * </ul>
      *
      * @param chance chance of the leggings being dropped
@@ -0,0 +0,0 @@ public interface EntityEquipment {
      *
      * <ul>
      * <li>A drop chance of 0.0F will never drop
-     * <li>A drop chance of 1.0F will always drop
+     * <li>A drop chance of exactly 1.0F will always drop if killed by a player
+     * <li>A drop chance of greater than 1.0F will always drop if killed by anything
      * </ul>
      *
      * @return the chance of the boots being dropped (1 for non-{@link Mob})
@@ -0,0 +0,0 @@ public interface EntityEquipment {
      *
      * <ul>
      * <li>A drop chance of 0.0F will never drop
-     * <li>A drop chance of 1.0F will always drop
+     * <li>A drop chance of exactly 1.0F will always drop if killed by a player
+     * <li>A drop chance of greater than 1.0F will always drop if killed by anything
      * </ul>
      *
      * @param chance of the boots being dropped
diff --git a/src/main/java/org/bukkit/inventory/ItemFlag.java b/src/main/java/org/bukkit/inventory/ItemFlag.java
index 0000000000000000000000000000000000000000..0000000000000000000000000000000000000000 100644
--- a/src/main/java/org/bukkit/inventory/ItemFlag.java
+++ b/src/main/java/org/bukkit/inventory/ItemFlag.java
@@ -0,0 +0,0 @@ public enum ItemFlag {
      */
     HIDE_DYE,
     /**
-     * Setting to show/hide armor trim from leather armor.
+     * Setting to show/hide armor trim from armor.
      */
     HIDE_ARMOR_TRIM;
 }
diff --git a/src/main/java/org/bukkit/inventory/PlayerInventory.java b/src/main/java/org/bukkit/inventory/PlayerInventory.java
index 0000000000000000000000000000000000000000..0000000000000000000000000000000000000000 100644
--- a/src/main/java/org/bukkit/inventory/PlayerInventory.java
+++ b/src/main/java/org/bukkit/inventory/PlayerInventory.java
@@ -0,0 +0,0 @@ public interface PlayerInventory extends Inventory {
     public void setBoots(@Nullable ItemStack boots);
 
     /**
-     * Gets a copy of the item the player is currently holding
+     * Gets the item the player is currently holding
      * in their main hand.
      *
      * @return the currently held item
@@ -0,0 +0,0 @@ public interface PlayerInventory extends Inventory {
     void setItemInMainHand(@Nullable ItemStack item);
 
     /**
-     * Gets a copy of the item the player is currently holding
+     * Gets the item the player is currently holding
      * in their off hand.
      *
      * @return the currently held item
@@ -0,0 +0,0 @@ public interface PlayerInventory extends Inventory {
     void setItemInOffHand(@Nullable ItemStack item);
 
     /**
-     * Gets a copy of the item the player is currently holding
+     * Gets the item the player is currently holding
      *
      * @return the currently held item
      * @see #getItemInMainHand()
diff --git a/src/main/java/org/bukkit/inventory/ShapedRecipe.java b/src/main/java/org/bukkit/inventory/ShapedRecipe.java
index 0000000000000000000000000000000000000000..0000000000000000000000000000000000000000 100644
--- a/src/main/java/org/bukkit/inventory/ShapedRecipe.java
+++ b/src/main/java/org/bukkit/inventory/ShapedRecipe.java
@@ -0,0 +0,0 @@ public class ShapedRecipe extends CraftingRecipe {
      * @param result The item you want the recipe to create.
      * @see ShapedRecipe#shape(String...)
      * @see ShapedRecipe#setIngredient(char, Material)
-     * @see ShapedRecipe#setIngredient(char, Material, int)
-     * @see ShapedRecipe#setIngredient(char, MaterialData)
      * @see ShapedRecipe#setIngredient(char, RecipeChoice)
      * @deprecated Recipes must have keys. Use {@link #ShapedRecipe(NamespacedKey, ItemStack)}
      * instead.
@@ -0,0 +0,0 @@ public class ShapedRecipe extends CraftingRecipe {
      * @exception IllegalArgumentException if the {@code result} is an empty item (AIR)
      * @see ShapedRecipe#shape(String...)
      * @see ShapedRecipe#setIngredient(char, Material)
-     * @see ShapedRecipe#setIngredient(char, Material, int)
-     * @see ShapedRecipe#setIngredient(char, MaterialData)
      * @see ShapedRecipe#setIngredient(char, RecipeChoice)
      */
     public ShapedRecipe(@NotNull NamespacedKey key, @NotNull ItemStack result) {
diff --git a/src/main/java/org/bukkit/inventory/ShapelessRecipe.java b/src/main/java/org/bukkit/inventory/ShapelessRecipe.java
index 0000000000000000000000000000000000000000..0000000000000000000000000000000000000000 100644
--- a/src/main/java/org/bukkit/inventory/ShapelessRecipe.java
+++ b/src/main/java/org/bukkit/inventory/ShapelessRecipe.java
@@ -0,0 +0,0 @@ public class ShapelessRecipe extends CraftingRecipe {
      * @param result The item you want the recipe to create.
      * @exception IllegalArgumentException if the {@code result} is an empty item (AIR)
      * @see ShapelessRecipe#addIngredient(Material)
-     * @see ShapelessRecipe#addIngredient(MaterialData)
-     * @see ShapelessRecipe#addIngredient(Material,int)
      * @see ShapelessRecipe#addIngredient(int,Material)
-     * @see ShapelessRecipe#addIngredient(int,MaterialData)
-     * @see ShapelessRecipe#addIngredient(int,Material,int)
+     * @see ShapelessRecipe#addIngredient(RecipeChoice)
      */
     public ShapelessRecipe(@NotNull NamespacedKey key, @NotNull ItemStack result) {
         super(key, checkResult(result));
@@ -0,0 +0,0 @@ public class ShapelessRecipe extends CraftingRecipe {
 
     /**
      * Removes multiple instances of an ingredient from the list. If there are
-     * less instances then specified, all will be removed. Only removes exact
+     * fewer instances than specified, all will be removed. Only removes exact
      * matches, with a data value of 0.
      *
      * @param count The number of copies to remove.
diff --git a/src/main/java/org/bukkit/inventory/StonecuttingRecipe.java b/src/main/java/org/bukkit/inventory/StonecuttingRecipe.java
index 0000000000000000000000000000000000000000..0000000000000000000000000000000000000000 100644
--- a/src/main/java/org/bukkit/inventory/StonecuttingRecipe.java
+++ b/src/main/java/org/bukkit/inventory/StonecuttingRecipe.java
@@ -0,0 +0,0 @@ public class StonecuttingRecipe implements Recipe, Keyed {
     }
 
     /**
-     * Create a cooking recipe to craft the specified ItemStack.
+     * Create a Stonecutting recipe to craft the specified ItemStack.
      *
      * @param key The unique recipe key
      * @param result The item you want the recipe to create.
@@ -0,0 +0,0 @@ public class StonecuttingRecipe implements Recipe, Keyed {
     }
 
     /**
-     * Sets the input of this cooking recipe.
+     * Sets the input of this Stonecutting recipe.
      *
      * @param input The input material.
      * @return The changed recipe, so you can chain calls.
@@ -0,0 +0,0 @@ public class StonecuttingRecipe implements Recipe, Keyed {
     }
 
     /**
-     * Sets the input of this cooking recipe.
+     * Sets the input of this Stonecutting recipe.
      *
      * @param input The input choice.
      * @return The changed recipe, so you can chain calls.
diff --git a/src/main/java/org/bukkit/inventory/meta/BlockStateMeta.java b/src/main/java/org/bukkit/inventory/meta/BlockStateMeta.java
index 0000000000000000000000000000000000000000..0000000000000000000000000000000000000000 100644
--- a/src/main/java/org/bukkit/inventory/meta/BlockStateMeta.java
+++ b/src/main/java/org/bukkit/inventory/meta/BlockStateMeta.java
@@ -0,0 +0,0 @@ public interface BlockStateMeta extends ItemMeta {
      * @param blockState the block state to attach to the block.
      * @throws IllegalArgumentException if the blockState is null
      *         or invalid for this item.
+     *
+     * @apiNote As of 1.20.5 the block state carries a copy of the item's data deviations.
+     * As such, setting the block state via this method will reset secondary deviations of the item meta.
+     * This can manifest in the addition to an existing lore failing or a change of a previously added display name.
+     * It is hence recommended to first mutate the block state, set it back, and then mutate the item meta.
      */
     void setBlockState(@NotNull BlockState blockState);
 }
diff --git a/src/main/java/org/bukkit/inventory/meta/CrossbowMeta.java b/src/main/java/org/bukkit/inventory/meta/CrossbowMeta.java
index 0000000000000000000000000000000000000000..0000000000000000000000000000000000000000 100644
--- a/src/main/java/org/bukkit/inventory/meta/CrossbowMeta.java
+++ b/src/main/java/org/bukkit/inventory/meta/CrossbowMeta.java
@@ -0,0 +0,0 @@ public interface CrossbowMeta extends ItemMeta {
      * Removes all projectiles when given null.
      *
      * @param projectiles the projectiles to set
-     * @throws IllegalArgumentException if one of the projectiles is not an
-     * arrow or firework rocket
+     * @throws IllegalArgumentException if one of the projectiles is empty
      */
     void setChargedProjectiles(@Nullable List<ItemStack> projectiles);
 
@@ -0,0 +0,0 @@ public interface CrossbowMeta extends ItemMeta {
      * Adds a charged projectile to this item.
      *
      * @param item projectile
-     * @throws IllegalArgumentException if the projectile is not an arrow or
-     * firework rocket
+     * @throws IllegalArgumentException if the projectile is empty
      */
     void addChargedProjectile(@NotNull ItemStack item);
 }
diff --git a/src/main/java/org/bukkit/inventory/meta/FireworkMeta.java b/src/main/java/org/bukkit/inventory/meta/FireworkMeta.java
index 0000000000000000000000000000000000000000..0000000000000000000000000000000000000000 100644
--- a/src/main/java/org/bukkit/inventory/meta/FireworkMeta.java
+++ b/src/main/java/org/bukkit/inventory/meta/FireworkMeta.java
@@ -0,0 +0,0 @@ public interface FireworkMeta extends ItemMeta {
      * Sets the approximate power of the firework. Each level of power is half
      * a second of flight time.
      *
-     * @param power the power of the firework, from 0-127
-     * @throws IllegalArgumentException if {@literal height<0 or height>127}
+     * @param power the power of the firework, from 0-255
+     * @throws IllegalArgumentException if {@literal power < 0 or power > 255}
      */
     void setPower(int power) throws IllegalArgumentException;
 
diff --git a/src/main/java/org/bukkit/inventory/meta/ItemMeta.java b/src/main/java/org/bukkit/inventory/meta/ItemMeta.java
index 0000000000000000000000000000000000000000..0000000000000000000000000000000000000000 100644
--- a/src/main/java/org/bukkit/inventory/meta/ItemMeta.java
+++ b/src/main/java/org/bukkit/inventory/meta/ItemMeta.java
@@ -0,0 +0,0 @@ public interface ItemMeta extends Cloneable, ConfigurationSerializable, Persiste
      * The returned component is a snapshot of its current state and does not
      * reflect a live view of what is on an item. After changing any value on
      * this component, it must be set with
-     * {@link #setJukeboxPlayable(org.bukkit.inventory.meta.components.JukeboxComponent)}
+     * {@link #setJukeboxPlayable(org.bukkit.inventory.meta.components.JukeboxPlayableComponent)}
      * to apply the changes.
      *
      * @return component
@@ -0,0 +0,0 @@ public interface ItemMeta extends Cloneable, ConfigurationSerializable, Persiste
     JukeboxPlayableComponent getJukeboxPlayable();
 
     /**
-     * Sets the item tool.
+     * Sets the jukebox playable component.
      *
      * @param jukeboxPlayable new component
      */
@@ -0,0 +0,0 @@ public interface ItemMeta extends Cloneable, ConfigurationSerializable, Persiste
     /**
      * Return an immutable copy of all {@link Attribute}s and their
      * {@link AttributeModifier}s for a given {@link EquipmentSlot}.<br>
-     * Any {@link AttributeModifier} that does have have a given
+     * Any {@link AttributeModifier} that does have a given
      * {@link EquipmentSlot} will be returned. This is because
      * AttributeModifiers without a slot are active in any slot.<br>
      * If there are no attributes set for the given slot, an empty map
diff --git a/src/main/java/org/bukkit/inventory/meta/LeatherArmorMeta.java b/src/main/java/org/bukkit/inventory/meta/LeatherArmorMeta.java
index 0000000000000000000000000000000000000000..0000000000000000000000000000000000000000 100644
--- a/src/main/java/org/bukkit/inventory/meta/LeatherArmorMeta.java
+++ b/src/main/java/org/bukkit/inventory/meta/LeatherArmorMeta.java
@@ -0,0 +0,0 @@ import org.jetbrains.annotations.Nullable;
 
 /**
  * Represents leather armor ({@link Material#LEATHER_BOOTS}, {@link
- * Material#LEATHER_CHESTPLATE}, {@link Material#LEATHER_HELMET}, or {@link
- * Material#LEATHER_LEGGINGS}) that can be colored.
+ * Material#LEATHER_LEGGINGS}, {@link Material#LEATHER_CHESTPLATE}, {@link
+ * Material#LEATHER_HELMET}, {@link Material#LEATHER_HORSE_ARMOR} or {@link
+ * Material#WOLF_ARMOR}) that can be colored.
  */
 public interface LeatherArmorMeta extends ItemMeta {
 
@@ -0,0 +0,0 @@ public interface LeatherArmorMeta extends ItemMeta {
      * be {@link ItemFactory#getDefaultLeatherColor()}.
      *
      * @return the color of the armor, never null
+     * @apiNote The method yielding {@link ItemFactory#getDefaultLeatherColor()} is incorrect
+     * for {@link Material#WOLF_ARMOR} as its default color differs. Generally, it is recommended to check
+     * {@link #isDyed()} to determine if this leather armor is dyed than to compare this color to the default.
      */
     @NotNull
     Color getColor();
@@ -0,0 +0,0 @@ public interface LeatherArmorMeta extends ItemMeta {
     /**
      * Sets the color of the armor.
      *
-     * @param color the color to set. Setting it to null is equivalent to
-     *     setting it to {@link ItemFactory#getDefaultLeatherColor()}.
+     * @param color the color to set.
      */
     void setColor(@Nullable Color color);
 
diff --git a/src/main/java/org/bukkit/inventory/meta/OminousBottleMeta.java b/src/main/java/org/bukkit/inventory/meta/OminousBottleMeta.java
index 0000000000000000000000000000000000000000..0000000000000000000000000000000000000000 100644
--- a/src/main/java/org/bukkit/inventory/meta/OminousBottleMeta.java
+++ b/src/main/java/org/bukkit/inventory/meta/OminousBottleMeta.java
@@ -0,0 +0,0 @@ package org.bukkit.inventory.meta;
 import org.jetbrains.annotations.NotNull;
 
 /**
- * Represents a map that can be scalable.
+ * Represents an ominous bottle with an amplifier of the bad omen effect.
  */
 public interface OminousBottleMeta extends ItemMeta {
 
diff --git a/src/main/java/org/bukkit/plugin/Plugin.java b/src/main/java/org/bukkit/plugin/Plugin.java
index 0000000000000000000000000000000000000000..0000000000000000000000000000000000000000 100644
--- a/src/main/java/org/bukkit/plugin/Plugin.java
+++ b/src/main/java/org/bukkit/plugin/Plugin.java
@@ -0,0 +0,0 @@ import org.jetbrains.annotations.Nullable;
  */
 public interface Plugin extends TabExecutor {
     /**
-     * Returns the folder that the plugin data's files are located in. The
+     * Returns the folder that the plugin data files are located in. The
      * folder may not yet exist.
      *
      * @return The folder
@@ -0,0 +0,0 @@ public interface Plugin extends TabExecutor {
     public File getDataFolder();
 
     /**
-     * Returns the plugin.yaml file containing the details for this plugin
+     * Returns the plugin.yml file containing the details for this plugin
      *
-     * @return Contents of the plugin.yaml file
+     * @return Contents of the plugin.yml file
      * @deprecated May be inaccurate due to different plugin implementations.
      * @see Plugin#getPluginMeta()
      */
diff --git a/src/main/java/org/bukkit/plugin/java/JavaPlugin.java b/src/main/java/org/bukkit/plugin/java/JavaPlugin.java
index 0000000000000000000000000000000000000000..0000000000000000000000000000000000000000 100644
--- a/src/main/java/org/bukkit/plugin/java/JavaPlugin.java
+++ b/src/main/java/org/bukkit/plugin/java/JavaPlugin.java
@@ -0,0 +0,0 @@ public abstract class JavaPlugin extends PluginBase {
     }
 
     /**
-     * Returns the folder that the plugin data's files are located in. The
+     * Returns the folder that the plugin data files are located in. The
      * folder may not yet exist.
      *
      * @return The folder.
@@ -0,0 +0,0 @@ public abstract class JavaPlugin extends PluginBase {
     }
 
     /**
-     * Returns the plugin.yaml file containing the details for this plugin
+     * Returns the plugin.yml file containing the details for this plugin
      *
-     * @return Contents of the plugin.yaml file
+     * @return Contents of the plugin.yml file
      * @deprecated No longer applicable to all types of plugins
      */
     @NotNull
diff --git a/src/main/java/org/bukkit/plugin/messaging/PluginMessageRecipient.java b/src/main/java/org/bukkit/plugin/messaging/PluginMessageRecipient.java
index 0000000000000000000000000000000000000000..0000000000000000000000000000000000000000 100644
--- a/src/main/java/org/bukkit/plugin/messaging/PluginMessageRecipient.java
+++ b/src/main/java/org/bukkit/plugin/messaging/PluginMessageRecipient.java
@@ -0,0 +0,0 @@ public interface PluginMessageRecipient {
 
     /**
      * Gets a set containing all the Plugin Channels that this client is
-     * listening on.
+     * listening on. Does not contain the BungeeCord channel due to its
+     * special status.
      *
      * @return Set containing all the channels that this client may accept.
      */
diff --git a/src/main/java/org/bukkit/scoreboard/Objective.java b/src/main/java/org/bukkit/scoreboard/Objective.java
index 0000000000000000000000000000000000000000..0000000000000000000000000000000000000000 100644
--- a/src/main/java/org/bukkit/scoreboard/Objective.java
+++ b/src/main/java/org/bukkit/scoreboard/Objective.java
@@ -0,0 +0,0 @@ public interface Objective {
      *
      * @return true if scores are modifiable
      * @throws IllegalStateException if this objective has been unregistered
-     * @see Criterias#HEALTH
+     * @see Criteria#HEALTH
      */
     boolean isModifiable();
 
diff --git a/src/main/java/org/bukkit/scoreboard/Team.java b/src/main/java/org/bukkit/scoreboard/Team.java
index 0000000000000000000000000000000000000000..0000000000000000000000000000000000000000 100644
--- a/src/main/java/org/bukkit/scoreboard/Team.java
+++ b/src/main/java/org/bukkit/scoreboard/Team.java
@@ -0,0 +0,0 @@ public interface Team extends net.kyori.adventure.audience.ForwardingAudience {
      * Gets the Set of entries on the team
      *
      * @return entries on the team
-     * @throws IllegalStateException if this entries has been unregistered
+     * @throws IllegalStateException if this team has been unregistered
      */
     @NotNull
     Set<String> getEntries();
diff --git a/src/main/java/org/bukkit/util/BoundingBox.java b/src/main/java/org/bukkit/util/BoundingBox.java
index 0000000000000000000000000000000000000000..0000000000000000000000000000000000000000 100644
--- a/src/main/java/org/bukkit/util/BoundingBox.java
+++ b/src/main/java/org/bukkit/util/BoundingBox.java
@@ -0,0 +0,0 @@ public class BoundingBox implements Cloneable, ConfigurationSerializable {
      * <p>
      * Negative values will shrink the bounding box in the corresponding
      * direction. Shrinking will be limited to the point where the affected
-     * opposite faces would meet if the they shrank at uniform speeds.
+     * opposite faces would meet if they shrank at uniform speeds.
      *
      * @param negativeX the amount of expansion in the negative x direction
      * @param negativeY the amount of expansion in the negative y direction
diff --git a/src/main/java/org/bukkit/util/CachedServerIcon.java b/src/main/java/org/bukkit/util/CachedServerIcon.java
index 0000000000000000000000000000000000000000..0000000000000000000000000000000000000000 100644
--- a/src/main/java/org/bukkit/util/CachedServerIcon.java
+++ b/src/main/java/org/bukkit/util/CachedServerIcon.java
@@ -0,0 +0,0 @@ import org.bukkit.event.server.ServerListPingEvent;
 import org.jetbrains.annotations.Nullable;
 
 /**
- * This is a cached version of a server-icon. It's internal representation
+ * This is a cached version of a server-icon. Its internal representation
  * and implementation is undefined.
  *
  * @see Server#getServerIcon()