Clean up the javadoc to pass java 8's doclint

By: Thinkofdeath <thinkofdeath@spigotmc.org>

paper-api/src/main/java/org/bukkit/event/EventHandler.java

@@ -24,6 +24,8 @@ public @interface EventHandler {
      * <li>HIGHEST
      * <li>MONITOR
      * </ol>
+     * 
+     * @return the priority
      */
     EventPriority priority() default EventPriority.NORMAL;
 
@@ -32,6 +34,8 @@ public @interface EventHandler {
      * <p>
      * If ignoreCancelled is true and the event is cancelled, the method is
      * not called. Otherwise, the method is always called.
+     * 
+     * @return whether cancelled events should be ignored
      */
     boolean ignoreCancelled() default false;
 }

paper-api/src/main/java/org/bukkit/event/block/BlockCanBuildEvent.java

@@ -29,6 +29,9 @@ public class BlockCanBuildEvent extends BlockEvent {
     /**
      *
      * @deprecated Magic value
+     * @param block the block involved in this event
+     * @param id the id of the block to place
+     * @param canBuild whether we can build 
      */
     @Deprecated
     public BlockCanBuildEvent(final Block block, final int id, final boolean canBuild) {

paper-api/src/main/java/org/bukkit/event/block/BlockIgniteEvent.java

@@ -19,10 +19,6 @@ public class BlockIgniteEvent extends BlockEvent implements Cancellable {
     private final Block ignitingBlock;
     private boolean cancel;
 
-    /**
-     * @deprecated use {@link BlockIgniteEvent#BlockIgniteEvent(Block,
-     * IgniteCause, Entity)} instead.
-     */
     @Deprecated
     public BlockIgniteEvent(final Block theBlock, final IgniteCause cause, final Player thePlayer) {
         this(theBlock, cause, (Entity) thePlayer);

paper-api/src/main/java/org/bukkit/event/block/BlockPhysicsEvent.java

@@ -16,6 +16,8 @@ public class BlockPhysicsEvent extends BlockEvent implements Cancellable {
     /**
      *
      * @deprecated Magic value
+     * @param block the block involved in this event
+     * @param changed the changed block's type id
      */
     @Deprecated
     public BlockPhysicsEvent(final Block block, final int changed) {

paper-api/src/main/java/org/bukkit/event/block/SignChangeEvent.java

@@ -46,8 +46,8 @@ public class SignChangeEvent extends BlockEvent implements Cancellable {
      * @param index index of the line to get
      * @return the String containing the line of text associated with the
      *     provided index
-     * @throws IndexOutOfBoundsException thrown when the provided index is > 3
-     *     or < 0
+     * @throws IndexOutOfBoundsException thrown when the provided index is {@literal > 3
+     *     or < 0}
      */
     public String getLine(int index) throws IndexOutOfBoundsException {
         return lines[index];
@@ -58,8 +58,8 @@ public class SignChangeEvent extends BlockEvent implements Cancellable {
      *
      * @param index index of the line to set
      * @param line text to set
-     * @throws IndexOutOfBoundsException thrown when the provided index is > 3
-     *     or < 0
+     * @throws IndexOutOfBoundsException thrown when the provided index is {@literal > 3
+     *     or < 0}
      */
     public void setLine(int index, String line) throws IndexOutOfBoundsException {
         lines[index] = line;

paper-api/src/main/java/org/bukkit/event/entity/EntityDamageEvent.java

@@ -63,6 +63,7 @@ public class EntityDamageEvent extends EntityEvent implements Cancellable {
      * event's construction.
      *
      * @param type the modifier
+     * @return the original damage
      * @throws IllegalArgumentException if type is null
      */
     public double getOriginalDamage(DamageModifier type) throws IllegalArgumentException {
@@ -79,6 +80,7 @@ public class EntityDamageEvent extends EntityEvent implements Cancellable {
     /**
      * Sets the damage for the specified modifier.
      *
+     * @param type the damage modifier
      * @param damage the scalar value of the damage's modifier
      * @see #getFinalDamage()
      * @throws IllegalArgumentException if type is null
@@ -96,6 +98,7 @@ public class EntityDamageEvent extends EntityEvent implements Cancellable {
     /**
      * Gets the damage change for some modifier
      *
+     * @param type the damage modifier
      * @return The raw amount of damage caused by the event
      * @throws IllegalArgumentException if type is null
      * @see DamageModifier#BASE
@@ -150,6 +153,8 @@ public class EntityDamageEvent extends EntityEvent implements Cancellable {
      * This method exists for legacy reasons to provide backwards
      * compatibility. It will not exist at runtime and should not be used
      * under any circumstances.
+     * 
+     * @return the (rounded) damage
      */
     @Deprecated
     public int _INVALID_getDamage() {
@@ -197,6 +202,8 @@ public class EntityDamageEvent extends EntityEvent implements Cancellable {
      * This method exists for legacy reasons to provide backwards
      * compatibility. It will not exist at runtime and should not be used
      * under any circumstances.
+     * 
+     * @param damage the new damage value
      */
     @Deprecated
     public void _INVALID_setDamage(int damage) {

paper-api/src/main/java/org/bukkit/event/entity/EntityPortalExitEvent.java

@@ -26,7 +26,7 @@ public class EntityPortalExitEvent extends EntityTeleportEvent {
      * Gets a copy of the velocity that the entity has before entering the
      * portal.
      *
-     * @return velocity of entity before entering portal
+     * @return velocity of entity before entering the portal
      */
     public Vector getBefore() {
         return this.before.clone();
@@ -36,7 +36,7 @@ public class EntityPortalExitEvent extends EntityTeleportEvent {
      * Gets a copy of the velocity that the entity will have after exiting the
      * portal.
      *
-     * @return velocity of entity after exiting portal
+     * @return velocity of entity after exiting the portal
      */
     public Vector getAfter() {
         return this.after.clone();
@@ -44,6 +44,8 @@ public class EntityPortalExitEvent extends EntityTeleportEvent {
 
     /**
      * Sets the velocity that the entity will have after exiting the portal.
+     * 
+     * @param after the velocity after exiting the portal
      */
     public void setAfter(Vector after) {
         this.after = after.clone();

paper-api/src/main/java/org/bukkit/event/entity/EntityRegainHealthEvent.java

@@ -38,6 +38,8 @@ public class EntityRegainHealthEvent extends EntityEvent implements Cancellable
      * This method exists for legacy reasons to provide backwards
      * compatibility. It will not exist at runtime and should not be used
      * under any circumstances.
+     * 
+     * @return the (rounded) amount regained
      */
     @Deprecated
     public int _INVALID_getAmount() {
@@ -57,16 +59,20 @@ public class EntityRegainHealthEvent extends EntityEvent implements Cancellable
      * This method exists for legacy reasons to provide backwards
      * compatibility. It will not exist at runtime and should not be used
      * under any circumstances.
+     * 
+     * @param amount the amount that will be regained
      */
     @Deprecated
     public void _INVALID_setAmount(int amount) {
         setAmount(amount);
     }
 
+    @Override
     public boolean isCancelled() {
         return cancelled;
     }
 
+    @Override
     public void setCancelled(boolean cancel) {
         cancelled = cancel;
     }

paper-api/src/main/java/org/bukkit/event/player/PlayerFishEvent.java

@@ -20,9 +20,9 @@ public class PlayerFishEvent extends PlayerEvent implements Cancellable {
     /**
      * @deprecated replaced by {@link #PlayerFishEvent(Player, Entity, Fish,
      *     State)} to include the {@link Fish} hook entity.
-     * @param player
-     * @param entity
-     * @param state
+     * @param player the player fishing
+     * @param entity the caught entity
+     * @param state the state of fishing
      */
     @Deprecated
     public PlayerFishEvent(final Player player, final Entity entity, final State state) {
@@ -40,7 +40,7 @@ public class PlayerFishEvent extends PlayerEvent implements Cancellable {
      * Gets the entity caught by the player.
      * <p>
      * If player has fished successfully, the result may be cast to {@link
-     * Item}.
+     * org.bukkit.entity.Item}.
      *
      * @return Entity caught by the player, Entity if fishing, and null if
      *     bobber has gotten stuck in the ground or nothing has been caught

paper-api/src/main/java/org/bukkit/event/player/PlayerLoginEvent.java

@@ -17,6 +17,7 @@ public class PlayerLoginEvent extends PlayerEvent {
 
     /**
      * @deprecated Address should be provided in other constructor
+     * @param player The {@link Player} for this event
      */
     @Deprecated
     public PlayerLoginEvent(final Player player) {
@@ -25,6 +26,8 @@ public class PlayerLoginEvent extends PlayerEvent {
 
     /**
      * @deprecated Address should be provided in other constructor
+     * @param player The {@link Player} for this event
+     * @param hostname The hostname that was used to connect to the server
      */
     @Deprecated
     public PlayerLoginEvent(final Player player, final String hostname) {
@@ -49,6 +52,9 @@ public class PlayerLoginEvent extends PlayerEvent {
     /**
      * @deprecated Address and hostname should be provided in other
      *     constructor
+     * @param player The {@link Player} for this event
+     * @param result The result status for this event
+     * @param message The message to be displayed if result denies login
      */
     @Deprecated
     public PlayerLoginEvent(final Player player, final Result result, final String message) {

paper-api/src/main/java/org/bukkit/event/server/ServerListPingEvent.java

@@ -32,6 +32,10 @@ public class ServerListPingEvent extends ServerEvent implements Iterable<Player>
      * This constructor is intended for implementations that provide the
      * {@link #iterator()} method, thus provided the {@link #getNumPlayers()}
      * count.
+     * 
+     * @param address the address of the pinger
+     * @param motd the message of the day
+     * @param maxPlayers the max number of players
      */
     protected ServerListPingEvent(final InetAddress address, final String motd, final int maxPlayers) {
         this.numPlayers = MAGIC_PLAYER_COUNT;

paper-api/src/main/java/org/bukkit/event/vehicle/VehicleDamageEvent.java

@@ -48,6 +48,8 @@ public class VehicleDamageEvent extends VehicleEvent implements Cancellable {
      * This method exists for legacy reasons to provide backwards
      * compatibility. It will not exist at runtime and should not be used
      * under any circumstances.
+     * 
+     * @return the damage
      */
     @Deprecated
     public int _INVALID_getDamage() {
@@ -67,6 +69,8 @@ public class VehicleDamageEvent extends VehicleEvent implements Cancellable {
      * This method exists for legacy reasons to provide backwards
      * compatibility. It will not exist at runtime and should not be used
      * under any circumstances.
+     * 
+     * @param damage the damage
      */
     @Deprecated
     public void _INVALID_setDamage(int damage) {

paper-api/src/main/java/org/bukkit/event/world/StructureGrowEvent.java

@@ -9,8 +9,8 @@ import org.bukkit.event.Cancellable;
 import org.bukkit.event.HandlerList;
 
 /**
- * Event that is called when an organic structure attempts to grow (Sapling ->
- * Tree), (Mushroom -> Huge Mushroom), naturally or using bonemeal.
+ * Event that is called when an organic structure attempts to grow (Sapling {@literal ->}
+ * Tree), (Mushroom {@literal ->} Huge Mushroom), naturally or using bonemeal.
  */
 public class StructureGrowEvent extends WorldEvent implements Cancellable {
     private static final HandlerList handlers = new HandlerList();