From e794550eeff1ff454e3507e15e356a6970004b5a Mon Sep 17 00:00:00 2001
From: Zach Brown <zach.brown@destroystokyo.com>
Date: Sat, 10 Jun 2017 16:59:40 -0500
Subject: [PATCH] Fix upstream javadoc warnings and errors

Upstream still refuses to use Java 8 with the API so they are likely unaware these are even issues.

diff --git a/src/main/java/org/bukkit/NamespacedKey.java b/src/main/java/org/bukkit/NamespacedKey.java
index 43239f84..fe8d3468 100644
--- a/src/main/java/org/bukkit/NamespacedKey.java
+++ b/src/main/java/org/bukkit/NamespacedKey.java
@@ -38,8 +38,8 @@ public final class NamespacedKey {
     /**
      * Create a key in a specific namespace.
      *
-     * @param namespace
-     * @param key
+     * @param namespace String representing a grouping of keys
+     * @param key Name for this specific key
      * @deprecated should never be used by plugins, for internal use only!!
      */
     @Deprecated
diff --git a/src/main/java/org/bukkit/World.java b/src/main/java/org/bukkit/World.java
index 013df5f8..14d1983a 100644
--- a/src/main/java/org/bukkit/World.java
+++ b/src/main/java/org/bukkit/World.java
@@ -1604,6 +1604,7 @@ public interface World extends PluginMessageRecipient, Metadatable {
      * @param count the number of particles
      * @param data the data to use for the particle or null,
      *             the type of this depends on {@link Particle#getDataType()}
+     * @param <T> Type
      */
     public <T> void spawnParticle(Particle particle, Location location, int count, T data);
 
@@ -1619,6 +1620,7 @@ public interface World extends PluginMessageRecipient, Metadatable {
      * @param count the number of particles
      * @param data the data to use for the particle or null,
      *             the type of this depends on {@link Particle#getDataType()}
+     * @param <T> Type
      */
     public <T> void spawnParticle(Particle particle, double x, double y, double z, int count, T data);
 
@@ -1668,6 +1670,7 @@ public interface World extends PluginMessageRecipient, Metadatable {
      * @param offsetZ the maximum random offset on the Z axis
      * @param data the data to use for the particle or null,
      *             the type of this depends on {@link Particle#getDataType()}
+     * @param <T> Type
      */
     public <T> void spawnParticle(Particle particle, Location location, int count, double offsetX, double offsetY, double offsetZ, T data);
 
@@ -1687,6 +1690,7 @@ public interface World extends PluginMessageRecipient, Metadatable {
      * @param offsetZ the maximum random offset on the Z axis
      * @param data the data to use for the particle or null,
      *             the type of this depends on {@link Particle#getDataType()}
+     * @param <T> Type
      */
     public <T> void spawnParticle(Particle particle, double x, double y, double z, int count, double offsetX, double offsetY, double offsetZ, T data);
 
@@ -1742,6 +1746,7 @@ public interface World extends PluginMessageRecipient, Metadatable {
      *              particle used (normally speed)
      * @param data the data to use for the particle or null,
      *             the type of this depends on {@link Particle#getDataType()}
+     * @param <T> Type
      */
     public <T> void spawnParticle(Particle particle, Location location, int count, double offsetX, double offsetY, double offsetZ, double extra, T data);
 
@@ -1763,6 +1768,7 @@ public interface World extends PluginMessageRecipient, Metadatable {
      *              particle used (normally speed)
      * @param data the data to use for the particle or null,
      *             the type of this depends on {@link Particle#getDataType()}
+     * @param <T> Type
      */
     public <T> void spawnParticle(Particle particle, double x, double y, double z, int count, double offsetX, double offsetY, double offsetZ, double extra, T data);
 
@@ -1785,6 +1791,7 @@ public interface World extends PluginMessageRecipient, Metadatable {
      * @param force whether to send the particle to players within an extended
      *              range and encourage their client to render it regardless of
      *              settings
+     * @param <T> Particle data type
      */
     public <T> void spawnParticle(Particle particle, Location location, int count, double offsetX, double offsetY, double offsetZ, double extra, T data, boolean force);
 
@@ -1809,6 +1816,7 @@ public interface World extends PluginMessageRecipient, Metadatable {
      * @param force whether to send the particle to players within an extended
      *              range and encourage their client to render it regardless of
      *              settings
+     * @param <T> Particle data type
      */
     public <T> void spawnParticle(Particle particle, double x, double y, double z, int count, double offsetX, double offsetY, double offsetZ, double extra, T data, boolean force);
 
diff --git a/src/main/java/org/bukkit/entity/AbstractHorse.java b/src/main/java/org/bukkit/entity/AbstractHorse.java
index 10757454..6d5410ea 100644
--- a/src/main/java/org/bukkit/entity/AbstractHorse.java
+++ b/src/main/java/org/bukkit/entity/AbstractHorse.java
@@ -22,7 +22,7 @@ public interface AbstractHorse extends Animals, Vehicle, InventoryHolder, Tameab
     public Horse.Variant getVariant();
 
     /**
-     * @param variant
+     * @param variant Variant to set
      * @deprecated you are required to spawn a different entity
      */
     @Deprecated
diff --git a/src/main/java/org/bukkit/entity/AreaEffectCloud.java b/src/main/java/org/bukkit/entity/AreaEffectCloud.java
index 9a569d3a..8c5efd17 100644
--- a/src/main/java/org/bukkit/entity/AreaEffectCloud.java
+++ b/src/main/java/org/bukkit/entity/AreaEffectCloud.java
@@ -138,6 +138,7 @@ public interface AreaEffectCloud extends Entity {
      * @param particle the new particle type
      * @param data the data to use for the particle or null,
      *             the type of this depends on {@link Particle#getDataType()}
+     * @param <T> the particle data type // Paper
      */
     <T> void setParticle(Particle particle, T data);
 
diff --git a/src/main/java/org/bukkit/entity/Guardian.java b/src/main/java/org/bukkit/entity/Guardian.java
index 98af0563..ec6890ae 100644
--- a/src/main/java/org/bukkit/entity/Guardian.java
+++ b/src/main/java/org/bukkit/entity/Guardian.java
@@ -12,7 +12,7 @@ public interface Guardian extends Monster {
     public boolean isElder();
 
     /**
-     * @param shouldBeElder
+     * @param shouldBeElder Sets whether the Guardian is an Elder
      * @deprecated Must spawn a new {@link ElderGuardian}.
      */
     @Deprecated
diff --git a/src/main/java/org/bukkit/entity/Horse.java b/src/main/java/org/bukkit/entity/Horse.java
index cfce8fa5..8660070b 100644
--- a/src/main/java/org/bukkit/entity/Horse.java
+++ b/src/main/java/org/bukkit/entity/Horse.java
@@ -151,7 +151,7 @@ public interface Horse extends AbstractHorse {
     public boolean isCarryingChest();
 
     /**
-     * @param chest
+     * @param chest Sets whether the Horse is carrying a chest
      * @deprecated see {@link ChestedHorse}
      */
     @Deprecated
diff --git a/src/main/java/org/bukkit/entity/Player.java b/src/main/java/org/bukkit/entity/Player.java
index d9965ddc..bf284f2c 100644
--- a/src/main/java/org/bukkit/entity/Player.java
+++ b/src/main/java/org/bukkit/entity/Player.java
@@ -431,7 +431,7 @@ 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
      */
     public void sendActionBar(char alternateChar, String message);
@@ -498,6 +498,7 @@ public interface Player extends HumanEntity, Conversable, OfflinePlayer, PluginM
     /**
      * Update the subtitle of titles displayed to the player
      *
+     * @param subtitle Subtitle to set
      * @deprecated Use {@link #updateTitle(Title)}
      */
     @Deprecated
@@ -506,6 +507,7 @@ public interface Player extends HumanEntity, Conversable, OfflinePlayer, PluginM
     /**
      * Update the subtitle of titles displayed to the player
      *
+     * @param subtitle Subtitle to set
      * @deprecated Use {@link #updateTitle(Title)}
      */
     @Deprecated
@@ -514,6 +516,7 @@ public interface Player extends HumanEntity, Conversable, OfflinePlayer, PluginM
     /**
      * Show the given title to the player, along with the last subtitle set, using the last set times
      *
+     * @param title Title to set
      * @deprecated Use {@link #sendTitle(Title)} or {@link #updateTitle(Title)}
      */
     @Deprecated
@@ -522,6 +525,7 @@ public interface Player extends HumanEntity, Conversable, OfflinePlayer, PluginM
     /**
      * Show the given title to the player, along with the last subtitle set, using the last set times
      *
+     * @param title Title to set
      * @deprecated Use {@link #sendTitle(Title)} or {@link #updateTitle(Title)}
      */
     @Deprecated
@@ -1418,6 +1422,7 @@ public interface Player extends HumanEntity, Conversable, OfflinePlayer, PluginM
      * @param count the number of particles
      * @param data the data to use for the particle or null,
      *             the type of this depends on {@link Particle#getDataType()}
+     * @param <T> Type
      */
     public <T> void spawnParticle(Particle particle, Location location, int count, T data);
 
@@ -1433,6 +1438,7 @@ public interface Player extends HumanEntity, Conversable, OfflinePlayer, PluginM
      * @param count the number of particles
      * @param data the data to use for the particle or null,
      *             the type of this depends on {@link Particle#getDataType()}
+     * @param <T> Type
      */
     public <T> void spawnParticle(Particle particle, double x, double y, double z, int count, T data);
 
@@ -1482,6 +1488,7 @@ public interface Player extends HumanEntity, Conversable, OfflinePlayer, PluginM
      * @param offsetZ the maximum random offset on the Z axis
      * @param data the data to use for the particle or null,
      *             the type of this depends on {@link Particle#getDataType()}
+     * @param <T> Type
      */
     public <T> void spawnParticle(Particle particle, Location location, int count, double offsetX, double offsetY, double offsetZ, T data);
 
@@ -1501,6 +1508,7 @@ public interface Player extends HumanEntity, Conversable, OfflinePlayer, PluginM
      * @param offsetZ the maximum random offset on the Z axis
      * @param data the data to use for the particle or null,
      *             the type of this depends on {@link Particle#getDataType()}
+     * @param <T> Type
      */
     public <T> void spawnParticle(Particle particle, double x, double y, double z, int count, double offsetX, double offsetY, double offsetZ, T data);
 
@@ -1556,6 +1564,7 @@ public interface Player extends HumanEntity, Conversable, OfflinePlayer, PluginM
      *              particle used (normally speed)
      * @param data the data to use for the particle or null,
      *             the type of this depends on {@link Particle#getDataType()}
+     * @param <T> Type
      */
     public <T> void spawnParticle(Particle particle, Location location, int count, double offsetX, double offsetY, double offsetZ, double extra, T data);
 
@@ -1577,6 +1586,7 @@ public interface Player extends HumanEntity, Conversable, OfflinePlayer, PluginM
      *              particle used (normally speed)
      * @param data the data to use for the particle or null,
      *             the type of this depends on {@link Particle#getDataType()}
+     * @param <T> Type
      */
     public <T> void spawnParticle(Particle particle, double x, double y, double z, int count, double offsetX, double offsetY, double offsetZ, double extra, T data);
 
diff --git a/src/main/java/org/bukkit/entity/Skeleton.java b/src/main/java/org/bukkit/entity/Skeleton.java
index 2a02ab85..e33d00b3 100644
--- a/src/main/java/org/bukkit/entity/Skeleton.java
+++ b/src/main/java/org/bukkit/entity/Skeleton.java
@@ -15,6 +15,7 @@ public interface Skeleton extends Monster {
     public SkeletonType getSkeletonType();
 
     /**
+     * @param type Type to set
      * @deprecated Must spawn a new subtype variant
      */
     @Deprecated
diff --git a/src/main/java/org/bukkit/entity/Zombie.java b/src/main/java/org/bukkit/entity/Zombie.java
index bdc6206a..48034198 100644
--- a/src/main/java/org/bukkit/entity/Zombie.java
+++ b/src/main/java/org/bukkit/entity/Zombie.java
@@ -29,14 +29,14 @@ public interface Zombie extends Monster {
     public boolean isVillager();
 
     /**
-     * @param flag
+     * @param flag Sets whether the Zombie is a villager
      * @deprecated must spawn {@link ZombieVillager}.
      */
     @Deprecated
     public void setVillager(boolean flag);
 
     /**
-     * @param profession
+     * @param profession Sets the ZombieVillager's profession
      * @see ZombieVillager#getVillagerProfession()
      */
     @Deprecated
diff --git a/src/main/java/org/bukkit/event/player/PlayerLoginEvent.java b/src/main/java/org/bukkit/event/player/PlayerLoginEvent.java
index 6532c24f..ee0b1273 100644
--- a/src/main/java/org/bukkit/event/player/PlayerLoginEvent.java
+++ b/src/main/java/org/bukkit/event/player/PlayerLoginEvent.java
@@ -28,6 +28,7 @@ public class PlayerLoginEvent extends PlayerEvent {
      * @param hostname The hostname that was used to connect to the server
      * @param address The address the player used to connect, provided for
      *     timing issues
+     * @param realAddress The unspoofed, actual address, that the player used to connect
      */
     public PlayerLoginEvent(final Player player, final String hostname, final InetAddress address, final InetAddress realAddress) { // Spigot
         super(player);
@@ -51,6 +52,7 @@ public class PlayerLoginEvent extends PlayerEvent {
      *     timing issues
      * @param result The result status for this event
      * @param message The message to be displayed if result denies login
+     * @param realAddress The unspoofed, actual address, that the player used to connect
      */
     public PlayerLoginEvent(final Player player, String hostname, final InetAddress address, final Result result, final String message, final InetAddress realAddress) { // Spigot
         this(player, hostname, address, realAddress); // Spigot
diff --git a/src/main/java/org/bukkit/inventory/ItemFactory.java b/src/main/java/org/bukkit/inventory/ItemFactory.java
index 762c43d6..ec2b8b8e 100644
--- a/src/main/java/org/bukkit/inventory/ItemFactory.java
+++ b/src/main/java/org/bukkit/inventory/ItemFactory.java
@@ -126,10 +126,10 @@ public interface ItemFactory {
      * Apply a material change for an item meta. Do not use under any
      * circumstances.
      *
-     * @param meta
-     * @param material
+     * @param meta meta
+     * @param material material
      * @return updated material
-     * @throws IllegalArgumentException
+     * @throws IllegalArgumentException exception
      * @deprecated for internal use only
      */
     @Deprecated
diff --git a/src/main/java/org/bukkit/inventory/Merchant.java b/src/main/java/org/bukkit/inventory/Merchant.java
index c8e68570..45431b36 100644
--- a/src/main/java/org/bukkit/inventory/Merchant.java
+++ b/src/main/java/org/bukkit/inventory/Merchant.java
@@ -32,7 +32,7 @@ public interface Merchant {
      *
      * @param i the index
      * @return the recipe
-     * @throws IndexOutOfBoundsException
+     * @throws IndexOutOfBoundsException Throws when specified index is larger than Merchant's inventory
      */
     MerchantRecipe getRecipe(int i) throws IndexOutOfBoundsException;
 
@@ -41,7 +41,7 @@ public interface Merchant {
      *
      * @param i the index
      * @param recipe the recipe
-     * @throws IndexOutOfBoundsException
+     * @throws IndexOutOfBoundsException Throws when specified index is larger than Merchant's inventory
      */
     void setRecipe(int i, MerchantRecipe recipe) throws IndexOutOfBoundsException;
 
diff --git a/src/main/java/org/bukkit/potion/Potion.java b/src/main/java/org/bukkit/potion/Potion.java
index 1413b361..b4a8051c 100644
--- a/src/main/java/org/bukkit/potion/Potion.java
+++ b/src/main/java/org/bukkit/potion/Potion.java
@@ -78,6 +78,7 @@ public class Potion {
     }
 
     /**
+     * @param name Unused, always uses {@link PotionType#WATER}
      * @deprecated
      */
     @Deprecated
diff --git a/src/main/java/org/bukkit/potion/PotionBrewer.java b/src/main/java/org/bukkit/potion/PotionBrewer.java
index 40f8d12b..33d19228 100644
--- a/src/main/java/org/bukkit/potion/PotionBrewer.java
+++ b/src/main/java/org/bukkit/potion/PotionBrewer.java
@@ -34,6 +34,8 @@ public interface PotionBrewer {
      * a potion with the given type.
      *
      * @param type The type of the potion
+     * @param upgraded Whether the potion is upgraded
+     * @param extended Whether the potion is extended
      * @return The list of effects
      */
     public Collection<PotionEffect> getEffects(PotionType type, boolean upgraded, boolean extended);
diff --git a/src/main/java/org/bukkit/potion/PotionType.java b/src/main/java/org/bukkit/potion/PotionType.java
index 034421a7..f1a54c23 100644
--- a/src/main/java/org/bukkit/potion/PotionType.java
+++ b/src/main/java/org/bukkit/potion/PotionType.java
@@ -68,6 +68,7 @@ public enum PotionType {
     }
 
     /**
+     * @return Damage value associated with this PotionType, broken
      * @deprecated Non-functional
      */
     @Deprecated
@@ -80,6 +81,8 @@ public enum PotionType {
     }
 
     /**
+     * @param damage Damage value associated with a PotionType
+     * @return PotionType for given damage value, broken
      * @deprecated Non-functional
      */
     @Deprecated
@@ -88,6 +91,8 @@ public enum PotionType {
     }
 
     /**
+     * @param effectType EffectType
+     * @return Associated PotionType
      * @deprecated Misleading
      */
     @Deprecated
diff --git a/src/main/java/org/bukkit/scoreboard/Team.java b/src/main/java/org/bukkit/scoreboard/Team.java
index ab71f3c3..358ea386 100644
--- a/src/main/java/org/bukkit/scoreboard/Team.java
+++ b/src/main/java/org/bukkit/scoreboard/Team.java
@@ -84,7 +84,7 @@ public interface Team {
      * names are handled by prefixes / suffixes.
      *
      * @return team color, defaults to {@link ChatColor#RESET}
-     * @throws IllegalStateException
+     * @throws IllegalStateException if this team has been unregistered
      */
     ChatColor getColor() throws IllegalStateException;
 
-- 
2.20.1