Fix upstream javadocs

2017-06-10 16:59:40 -05:00
parent f7eff332be
commit 0c37d20354
75 changed files with 403 additions and 173 deletions
--- a/paper-api/src/main/java/org/bukkit/event/block/BlockDropItemEvent.java
+++ b/paper-api/src/main/java/org/bukkit/event/block/BlockDropItemEvent.java
@@ -10,15 +10,19 @@ 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
--- a/paper-api/src/main/java/org/bukkit/event/block/BlockExplodeEvent.java
+++ b/paper-api/src/main/java/org/bukkit/event/block/BlockExplodeEvent.java
@@ -14,6 +14,9 @@ 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();
--- a/paper-api/src/main/java/org/bukkit/event/block/BlockPistonRetractEvent.java
+++ b/paper-api/src/main/java/org/bukkit/event/block/BlockPistonRetractEvent.java
@@ -34,7 +34,7 @@ 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.
     */
--- a/paper-api/src/main/java/org/bukkit/event/block/BlockPlaceEvent.java
+++ b/paper-api/src/main/java/org/bukkit/event/block/BlockPlaceEvent.java
@@ -114,7 +114,7 @@ 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.
--- a/paper-api/src/main/java/org/bukkit/event/enchantment/PrepareItemEnchantEvent.java
+++ b/paper-api/src/main/java/org/bukkit/event/enchantment/PrepareItemEnchantEvent.java
@@ -81,7 +81,7 @@ 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
--- a/paper-api/src/main/java/org/bukkit/event/entity/AreaEffectCloudApplyEvent.java
+++ b/paper-api/src/main/java/org/bukkit/event/entity/AreaEffectCloudApplyEvent.java
@@ -8,7 +8,7 @@ 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 {
--- a/paper-api/src/main/java/org/bukkit/event/entity/CreatureSpawnEvent.java
+++ b/paper-api/src/main/java/org/bukkit/event/entity/CreatureSpawnEvent.java
@@ -158,11 +158,12 @@ 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,
        /**
--- a/paper-api/src/main/java/org/bukkit/event/entity/EntityDamageByBlockEvent.java
+++ b/paper-api/src/main/java/org/bukkit/event/entity/EntityDamageByBlockEvent.java
@@ -12,6 +12,10 @@ 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;
@@ -51,6 +55,9 @@ 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
     */
--- a/paper-api/src/main/java/org/bukkit/event/entity/EntityExplodeEvent.java
+++ b/paper-api/src/main/java/org/bukkit/event/entity/EntityExplodeEvent.java
@@ -10,7 +10,9 @@ 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();
--- a/paper-api/src/main/java/org/bukkit/event/entity/EntityPickupItemEvent.java
+++ b/paper-api/src/main/java/org/bukkit/event/entity/EntityPickupItemEvent.java
@@ -7,7 +7,7 @@ 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();
--- a/paper-api/src/main/java/org/bukkit/event/entity/EntityPlaceEvent.java
+++ b/paper-api/src/main/java/org/bukkit/event/entity/EntityPlaceEvent.java
@@ -11,7 +11,7 @@ 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:
--- a/paper-api/src/main/java/org/bukkit/event/entity/EntityPotionEffectEvent.java
+++ b/paper-api/src/main/java/org/bukkit/event/entity/EntityPotionEffectEvent.java
@@ -133,7 +133,7 @@ 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,
@@ -237,7 +237,7 @@ 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,
        /**
--- a/paper-api/src/main/java/org/bukkit/event/entity/EntityRegainHealthEvent.java
+++ b/paper-api/src/main/java/org/bukkit/event/entity/EntityRegainHealthEvent.java
@@ -105,7 +105,7 @@ 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,
        /**
--- a/paper-api/src/main/java/org/bukkit/event/entity/EntityTargetEvent.java
+++ b/paper-api/src/main/java/org/bukkit/event/entity/EntityTargetEvent.java
@@ -156,7 +156,7 @@ 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,
        /**
--- a/paper-api/src/main/java/org/bukkit/event/entity/PiglinBarterEvent.java
+++ b/paper-api/src/main/java/org/bukkit/event/entity/PiglinBarterEvent.java
@@ -10,8 +10,7 @@ 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 {

--- a/paper-api/src/main/java/org/bukkit/event/inventory/FurnaceBurnEvent.java
+++ b/paper-api/src/main/java/org/bukkit/event/inventory/FurnaceBurnEvent.java
@@ -8,7 +8,9 @@ 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();
--- a/paper-api/src/main/java/org/bukkit/event/inventory/FurnaceExtractEvent.java
+++ b/paper-api/src/main/java/org/bukkit/event/inventory/FurnaceExtractEvent.java
@@ -9,7 +9,9 @@ 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;
--- a/paper-api/src/main/java/org/bukkit/event/inventory/FurnaceSmeltEvent.java
+++ b/paper-api/src/main/java/org/bukkit/event/inventory/FurnaceSmeltEvent.java
@@ -6,7 +6,9 @@ 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 {

--- a/paper-api/src/main/java/org/bukkit/event/inventory/FurnaceStartSmeltEvent.java
+++ b/paper-api/src/main/java/org/bukkit/event/inventory/FurnaceStartSmeltEvent.java
@@ -8,7 +8,10 @@ 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();
--- a/paper-api/src/main/java/org/bukkit/event/inventory/InventoryClickEvent.java
+++ b/paper-api/src/main/java/org/bukkit/event/inventory/InventoryClickEvent.java
@@ -16,12 +16,16 @@ 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)}
@@ -92,7 +96,7 @@ 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() {
--- a/paper-api/src/main/java/org/bukkit/event/inventory/InventoryCloseEvent.java
+++ b/paper-api/src/main/java/org/bukkit/event/inventory/InventoryCloseEvent.java
@@ -7,7 +7,26 @@ 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();
--- a/paper-api/src/main/java/org/bukkit/event/inventory/InventoryOpenEvent.java
+++ b/paper-api/src/main/java/org/bukkit/event/inventory/InventoryOpenEvent.java
@@ -7,7 +7,7 @@ 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();
--- a/paper-api/src/main/java/org/bukkit/event/inventory/PrepareAnvilEvent.java
+++ b/paper-api/src/main/java/org/bukkit/event/inventory/PrepareAnvilEvent.java
@@ -24,6 +24,20 @@ 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() {
--- a/paper-api/src/main/java/org/bukkit/event/player/PlayerCommandPreprocessEvent.java
+++ b/paper-api/src/main/java/org/bukkit/event/player/PlayerCommandPreprocessEvent.java
@@ -106,7 +106,9 @@ public class PlayerCommandPreprocessEvent extends PlayerEvent implements Cancell
     *
     * @param player New player which this event will execute as
     * @throws IllegalArgumentException if the player provided is null
+     * @deprecated Only works for sign commands; use {@link Player#performCommand(String)}, including those cases
     */
+    @Deprecated(forRemoval = true)
    public void setPlayer(@NotNull final Player player) throws IllegalArgumentException {
        Preconditions.checkArgument(player != null, "Player cannot be null");
        this.player = player;
@@ -123,11 +125,10 @@ public class PlayerCommandPreprocessEvent extends PlayerEvent implements Cancell
     * unmodifiable set.
     *
     * @return All Players who will see this chat message
-     * @deprecated This method is provided for backward compatibility with no
-     *     guarantee to the effect of viewing or modifying the set.
+     * @deprecated This is simply the online players. Modifications have no effect
     */
    @NotNull
-    @Deprecated(since = "1.3.1")
+    @Deprecated(since = "1.3.1", forRemoval = true)
    public Set<Player> getRecipients() {
        return recipients;
    }
--- a/paper-api/src/main/java/org/bukkit/event/player/PlayerResourcePackStatusEvent.java
+++ b/paper-api/src/main/java/org/bukkit/event/player/PlayerResourcePackStatusEvent.java
@@ -6,8 +6,9 @@ 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 {