docs: Minor javadoc changes to most of the api directory

common/src/main/java/com/hibiscusmc/hmccosmetics/api/events/PlayerCosmeticEquipEvent.java

@@ -6,8 +6,6 @@ import org.bukkit.event.Cancellable;
 import org.bukkit.event.HandlerList;
 import org.jetbrains.annotations.NotNull;
 
-import java.util.List;
-
 /**
  * Called when a player equips a {@link Cosmetic}.
  */
@@ -26,7 +24,7 @@ public class PlayerCosmeticEquipEvent extends PlayerCosmeticEvent implements Can
     /**
      * Gets the {@link Cosmetic} being equipped in this event.
      *
-     * @return the {@link Cosmetic} which is being equipped in this event
+     * @return the cosmetic which is being equipped in this event
      */
     @NotNull
     public Cosmetic getCosmetic() {
@@ -36,7 +34,7 @@ public class PlayerCosmeticEquipEvent extends PlayerCosmeticEvent implements Can
     /**
      * Sets the {@link Cosmetic} that the player will equip.
      *
-     * @param cosmetic the {@link Cosmetic} that the player will equip
+     * @param cosmetic the cosmetic that the player will equip
      */
     public void setCosmetic(@NotNull Cosmetic cosmetic) {
         this.cosmetic = cosmetic;

common/src/main/java/com/hibiscusmc/hmccosmetics/api/events/PlayerCosmeticHideEvent.java

@@ -23,7 +23,7 @@ public class PlayerCosmeticHideEvent extends PlayerCosmeticEvent implements Canc
     /**
      * Gets the {@link CosmeticUser.HiddenReason} as to why cosmetics are being hidden for the player.
      *
-     * @return the {@link CosmeticUser.HiddenReason} why cosmetics are being hidden for the player
+     * @return the reason why cosmetics are being hidden for the player
      */
     public @NotNull CosmeticUser.HiddenReason getReason() {
         return reason;

common/src/main/java/com/hibiscusmc/hmccosmetics/api/events/PlayerCosmeticPostEquipEvent.java

@@ -21,7 +21,7 @@ public class PlayerCosmeticPostEquipEvent extends PlayerCosmeticEvent {
     /**
      * Gets the {@link Cosmetic} being equipped in this event.
      *
-     * @return the {@link Cosmetic} which is being equipped in this event
+     * @return the cosmetic which is being equipped in this event
      */
     public @NotNull Cosmetic getCosmetic() {
         return cosmetic;
@@ -30,7 +30,7 @@ public class PlayerCosmeticPostEquipEvent extends PlayerCosmeticEvent {
     /**
      * Sets the {@link Cosmetic} that the player will equip.
      *
-     * @param cosmetic the {@link Cosmetic} that the player will equip
+     * @param cosmetic the cosmetic that the player will equip
      */
     public void setCosmetic(@NotNull Cosmetic cosmetic) {
         this.cosmetic = cosmetic;

common/src/main/java/com/hibiscusmc/hmccosmetics/api/events/PlayerCosmeticRemoveEvent.java

@@ -7,22 +7,24 @@ import org.bukkit.event.HandlerList;
 import org.jetbrains.annotations.NotNull;
 
 /**
- * Called when a player removes a cosmetic
+ * Called when a player removes a {@link Cosmetic}.
  */
 public class PlayerCosmeticRemoveEvent extends PlayerCosmeticEvent implements Cancellable {
-    private static final HandlerList handlers = new HandlerList();
-    private boolean cancel = false;
+    private static final HandlerList HANDLER_LIST = new HandlerList();
+
     private final Cosmetic cosmetic;
 
+    private boolean cancel = false;
+
     public PlayerCosmeticRemoveEvent(@NotNull CosmeticUser who, @NotNull Cosmetic cosmetic) {
         super(who);
         this.cosmetic = cosmetic;
     }
 
     /**
-     * Gets the {@link Cosmetic} being removed in this event
+     * Gets the {@link Cosmetic} being removed in this event.
      *
-     * @return The {@link Cosmetic} which is being removed in this event
+     * @return the cosmetic which is being removed in this event
      */
     public Cosmetic getCosmetic() {
         return cosmetic;
@@ -33,27 +35,17 @@ public class PlayerCosmeticRemoveEvent extends PlayerCosmeticEvent implements Ca
         return cancel;
     }
 
-    /**
-     * Sets the cancellation state of this event
-     *
-     * <p>
-     * Canceling this event will prevent the player from removing the cosmetic
-     * </p>
-     *
-     * @param cancel true if you wish to cancel this event
-     */
     @Override
     public void setCancelled(boolean cancel) {
         this.cancel = cancel;
     }
 
     @Override
-    @NotNull
-    public HandlerList getHandlers() {
-        return handlers;
+    public @NotNull HandlerList getHandlers() {
+        return HANDLER_LIST;
     }
 
-    public static HandlerList getHandlerList() {
-        return handlers;
+    public static @NotNull HandlerList getHandlerList() {
+        return HANDLER_LIST;
     }
 }

common/src/main/java/com/hibiscusmc/hmccosmetics/api/events/PlayerCosmeticShowEvent.java

@@ -6,10 +6,11 @@ import org.bukkit.event.HandlerList;
 import org.jetbrains.annotations.NotNull;
 
 /**
- * Called when cosmetics are shown from a player
+ * Called when cosmetics are shown from a player.
  */
 public class PlayerCosmeticShowEvent extends PlayerCosmeticEvent implements Cancellable {
-    private static final HandlerList handlers = new HandlerList();
+    private static final HandlerList HANDLER_LIST = new HandlerList();
+
     private boolean cancel = false;
 
     public PlayerCosmeticShowEvent(@NotNull CosmeticUser who) {
@@ -21,28 +22,17 @@ public class PlayerCosmeticShowEvent extends PlayerCosmeticEvent implements Canc
         return cancel;
     }
 
-    /**
-     * Sets the cancellation state of this event
-     *
-     * <p>
-     * Canceling this event will prevent the player from showing cosmetics
-     * </p>
-     *
-     * @param cancel true if you wish to cancel this event
-     */
     @Override
     public void setCancelled(boolean cancel) {
         this.cancel = cancel;
     }
 
     @Override
-    @NotNull
-    public HandlerList getHandlers() {
-        return handlers;
+    public @NotNull HandlerList getHandlers() {
+        return HANDLER_LIST;
     }
 
-    @NotNull
-    public static HandlerList getHandlerList() {
-        return handlers;
+    public static @NotNull HandlerList getHandlerList() {
+        return HANDLER_LIST;
     }
 }

common/src/main/java/com/hibiscusmc/hmccosmetics/api/events/PlayerEmoteStartEvent.java

@@ -6,23 +6,27 @@ import org.bukkit.event.HandlerList;
 import org.jetbrains.annotations.NotNull;
 
 /**
- * Called when a player starts playing an emote
+ * Called when a player starts playing an emote.
  */
 public class PlayerEmoteStartEvent extends PlayerCosmeticEvent implements Cancellable {
-    private static final HandlerList handlers = new HandlerList();
-    private boolean cancel = false;
+    private static final HandlerList HANDLER_LIST = new HandlerList();
+
     private final String animationId;
 
+    private boolean cancel = false;
+
     public PlayerEmoteStartEvent(@NotNull CosmeticUser who, @NotNull String animationId) {
         super(who);
         this.animationId = animationId;
     }
 
     /**
-     * Gets the animation id of the emote the player started playing
-     * @implNote The returned string of this method may be an invalid animation id. Make sure to validate it before use
+     * Gets the animation id of the emote the player started playing.
      *
-     * @return The animation id of the emote which the player started playing
+     * @implNote The returned string of this method may be an invalid animation id.
+     * Make sure to validate it before use by calling {@link com.hibiscusmc.hmccosmetics.emotes.EmoteManager#get(String)}.
+     *
+     * @return the animation id of the emote which the player started playing
      */
     @NotNull
     public String getAnimationId() {
@@ -34,28 +38,17 @@ public class PlayerEmoteStartEvent extends PlayerCosmeticEvent implements Cancel
         return cancel;
     }
 
-    /**
-     * Sets the cancellation state of this event
-     *
-     * <p>
-     * Canceling this event will prevent the player from playing the emote
-     * </p>
-     *
-     * @param cancel true if you wish to cancel this event
-     */
     @Override
     public void setCancelled(boolean cancel) {
         this.cancel = cancel;
     }
 
     @Override
-    @NotNull
-    public HandlerList getHandlers() {
-        return handlers;
+    public @NotNull HandlerList getHandlers() {
+        return HANDLER_LIST;
     }
 
-    @NotNull
-    public static HandlerList getHandlerList() {
-        return handlers;
+    public static @NotNull HandlerList getHandlerList() {
+        return HANDLER_LIST;
     }
 }

common/src/main/java/com/hibiscusmc/hmccosmetics/api/events/PlayerEmoteStopEvent.java

@@ -7,13 +7,15 @@ import org.bukkit.event.HandlerList;
 import org.jetbrains.annotations.NotNull;
 
 /**
- * Called when a player stops playing an emote
+ * Called when a player stops playing an emote.
  */
 public class PlayerEmoteStopEvent extends PlayerCosmeticEvent implements Cancellable {
-    private static final HandlerList handlers = new HandlerList();
-    private boolean cancel = false;
+    private static final HandlerList HANDLER_LIST = new HandlerList();
+
     private final UserEmoteManager.StopEmoteReason reason;
 
+    private boolean cancel = false;
+
     public PlayerEmoteStopEvent(@NotNull CosmeticUser who, @NotNull UserEmoteManager.StopEmoteReason reason) {
         super(who);
         this.reason = reason;
@@ -25,20 +27,19 @@ public class PlayerEmoteStopEvent extends PlayerCosmeticEvent implements Cancell
      * @return The {@link UserEmoteManager.StopEmoteReason} why the emote has stopped playing
      * @deprecated As of release 2.2.5+, replaced by {@link #getReason()}
      */
-    @Deprecated
+    @Deprecated(forRemoval = true)
     @NotNull
     public UserEmoteManager.StopEmoteReason getStopEmoteReason() {
         return reason;
     }
 
     /**
-     * Gets the {@link UserEmoteManager.StopEmoteReason} as to why the emote has stopped playing
+     * Gets the {@link UserEmoteManager.StopEmoteReason} as to why the emote has stopped playing.
      *
-     * @return The {@link UserEmoteManager.StopEmoteReason} why the emote has stopped playing
+     * @return the reason why the emote has stopped playing
      * @since 2.2.5
      */
-    @NotNull
-    public UserEmoteManager.StopEmoteReason getReason() {
+    public @NotNull UserEmoteManager.StopEmoteReason getReason() {
         return reason;
     }
 
@@ -47,28 +48,17 @@ public class PlayerEmoteStopEvent extends PlayerCosmeticEvent implements Cancell
         return cancel;
     }
 
-    /**
-     * Sets the cancellation state of this event
-     *
-     * <p>
-     * Canceling this event will prevent the player from stopping the emote
-     * </p>
-     *
-     * @param cancel true if you wish to cancel this event
-     */
     @Override
     public void setCancelled(boolean cancel) {
         this.cancel = cancel;
     }
 
     @Override
-    @NotNull
-    public HandlerList getHandlers() {
-        return handlers;
+    public @NotNull HandlerList getHandlers() {
+        return HANDLER_LIST;
     }
 
-    @NotNull
-    public static HandlerList getHandlerList() {
-        return handlers;
+    public static @NotNull HandlerList getHandlerList() {
+        return HANDLER_LIST;
     }
 }

common/src/main/java/com/hibiscusmc/hmccosmetics/api/events/PlayerLoadEvent.java

@@ -4,22 +4,22 @@ import com.hibiscusmc.hmccosmetics.user.CosmeticUser;
 import org.bukkit.event.HandlerList;
 import org.jetbrains.annotations.NotNull;
 
+/**
+ * Called when a player's cosmetic data is loaded.
+ */
 public class PlayerLoadEvent extends PlayerCosmeticEvent {
-
-    private static final HandlerList handlers = new HandlerList();
+    private static final HandlerList HANDLER_LIST = new HandlerList();
 
     public PlayerLoadEvent(@NotNull CosmeticUser who) {
         super(who);
     }
 
     @Override
-    @NotNull
-    public HandlerList getHandlers() {
-        return handlers;
+    public @NotNull HandlerList getHandlers() {
+        return HANDLER_LIST;
     }
 
-    @NotNull
-    public static HandlerList getHandlerList() {
-        return handlers;
+    public static @NotNull HandlerList getHandlerList() {
+        return HANDLER_LIST;
     }
 }

common/src/main/java/com/hibiscusmc/hmccosmetics/api/events/PlayerMenuCloseEvent.java

@@ -6,23 +6,21 @@ import org.bukkit.event.HandlerList;
 import org.jetbrains.annotations.NotNull;
 
 /**
- * Called when a menu is closed by a player
+ * Called when a {@link Menu} is closed by a player.
  */
 public class PlayerMenuCloseEvent extends PlayerMenuEvent {
-    private static final HandlerList handlers = new HandlerList();
+    private static final HandlerList HANDLER_LIST = new HandlerList();
 
     public PlayerMenuCloseEvent(@NotNull CosmeticUser who, @NotNull Menu menu) {
         super(who, menu);
     }
 
     @Override
-    @NotNull
-    public HandlerList getHandlers() {
-        return handlers;
+    public @NotNull HandlerList getHandlers() {
+        return HANDLER_LIST;
     }
 
-    @NotNull
-    public static HandlerList getHandlerList() {
-        return handlers;
+    public static @NotNull HandlerList getHandlerList() {
+        return HANDLER_LIST;
     }
 }

common/src/main/java/com/hibiscusmc/hmccosmetics/api/events/PlayerMenuEvent.java

@@ -5,10 +5,10 @@ import com.hibiscusmc.hmccosmetics.user.CosmeticUser;
 import org.jetbrains.annotations.NotNull;
 
 /**
- * Represents a menu related event
+ * Represents an event related to a player's interaction with a {@link Menu}.
  */
 public abstract class PlayerMenuEvent extends PlayerCosmeticEvent {
-    protected Menu menu;
+    protected final Menu menu;
 
     public PlayerMenuEvent(@NotNull CosmeticUser who, @NotNull Menu menu) {
         super(who);
@@ -16,12 +16,11 @@ public abstract class PlayerMenuEvent extends PlayerCosmeticEvent {
     }
 
     /**
-     * Gets the {@link Menu} involved with this event
+     * Gets the {@link Menu} involved with this event.
      *
-     * @return The {@link Menu} which is involved with the event
+     * @return the menu involved in this event
      */
-    @NotNull
-    public final Menu getMenu() {
+    public @NotNull final Menu getMenu() {
         return menu;
     }
 }

common/src/main/java/com/hibiscusmc/hmccosmetics/api/events/PlayerMenuOpenEvent.java

@@ -7,10 +7,11 @@ import org.bukkit.event.HandlerList;
 import org.jetbrains.annotations.NotNull;
 
 /**
- * Called when a menu is opened by a player
+ * Called when a {@link Menu} is opened by a player.
  */
 public class PlayerMenuOpenEvent extends PlayerMenuEvent implements Cancellable {
-    private static final HandlerList handlers = new HandlerList();
+    private static final HandlerList HANDLER_LIST = new HandlerList();
+
     private boolean cancel = false;
 
     public PlayerMenuOpenEvent(@NotNull CosmeticUser who, @NotNull Menu menu) {
@@ -22,28 +23,17 @@ public class PlayerMenuOpenEvent extends PlayerMenuEvent implements Cancellable
         return cancel;
     }
 
-    /**
-     * Sets the cancellation state of this event
-     *
-     * <p>
-     * Canceling this event will prevent the player from opening a {@link Menu}
-     * </p>
-     *
-     * @param cancel true if you wish to cancel this event
-     */
     @Override
     public void setCancelled(boolean cancel) {
         this.cancel = cancel;
     }
 
     @Override
-    @NotNull
-    public HandlerList getHandlers() {
-        return handlers;
+    public @NotNull HandlerList getHandlers() {
+        return HANDLER_LIST;
     }
 
-    @NotNull
-    public static HandlerList getHandlerList() {
-        return handlers;
+    public static @NotNull HandlerList getHandlerList() {
+        return HANDLER_LIST;
     }
 }

common/src/main/java/com/hibiscusmc/hmccosmetics/api/events/PlayerPreLoadEvent.java

@@ -1,36 +1,28 @@
 package com.hibiscusmc.hmccosmetics.api.events;
 
 import org.bukkit.event.Cancellable;
-import org.bukkit.event.Event;
 import org.bukkit.event.HandlerList;
 import org.jetbrains.annotations.NotNull;
 
 import java.util.UUID;
 
 /**
- * Called before a player is loaded into the plugin (including before the plugin gets their data).
- * This event is cancellable, and if cancelled, the player will not be loaded into the plugin.
+ * Called before a player's data is loaded into the plugin.
+ *
+ * <p>
+ *     If this event is cancelled, the player's data will not be loaded,
+ *     and the player will not be able to interact with the plugin.
+ * </p>
  */
 public class PlayerPreLoadEvent extends PlayerEvent implements Cancellable {
+    private static final HandlerList HANDLER_LIST = new HandlerList();
 
-    private static final HandlerList handlers = new HandlerList();
     private boolean cancelled = false;
 
     public PlayerPreLoadEvent(@NotNull UUID id) {
         super(id);
     }
 
-    @Override
-    @NotNull
-    public HandlerList getHandlers() {
-        return handlers;
-    }
-
-    @NotNull
-    public static HandlerList getHandlerList() {
-        return handlers;
-    }
-
     @Override
     public boolean isCancelled() {
         return cancelled;
@@ -40,4 +32,13 @@ public class PlayerPreLoadEvent extends PlayerEvent implements Cancellable {
     public void setCancelled(boolean cancel) {
         this.cancelled = cancel;
     }
+
+    @Override
+    public @NotNull HandlerList getHandlers() {
+        return HANDLER_LIST;
+    }
+
+    public static @NotNull HandlerList getHandlerList() {
+        return HANDLER_LIST;
+    }
 }

common/src/main/java/com/hibiscusmc/hmccosmetics/api/events/PlayerUnloadEvent.java

@@ -4,23 +4,22 @@ import com.hibiscusmc.hmccosmetics.user.CosmeticUser;
 import org.bukkit.event.HandlerList;
 import org.jetbrains.annotations.NotNull;
 
+/**
+ * Called when a players data is unloaded from the plugin. This is called when a player leaves the server.
+ */
 public class PlayerUnloadEvent extends PlayerCosmeticEvent {
-
-    private static final HandlerList handlers = new HandlerList();
+    private static final HandlerList HANDLER_LIST = new HandlerList();
 
     public PlayerUnloadEvent(@NotNull CosmeticUser who) {
         super(who);
     }
 
     @Override
-    @NotNull
-    public HandlerList getHandlers() {
-        return handlers;
+    public @NotNull HandlerList getHandlers() {
+        return HANDLER_LIST;
     }
 
-    @NotNull
-    public static HandlerList getHandlerList() {
-        return handlers;
+    public static @NotNull HandlerList getHandlerList() {
+        return HANDLER_LIST;
     }
-
 }

common/src/main/java/com/hibiscusmc/hmccosmetics/api/events/PlayerWardrobeEnterEvent.java

@@ -2,19 +2,18 @@ package com.hibiscusmc.hmccosmetics.api.events;
 
 import com.hibiscusmc.hmccosmetics.config.Wardrobe;
 import com.hibiscusmc.hmccosmetics.user.CosmeticUser;
-import lombok.Getter;
-import lombok.Setter;
 import org.bukkit.event.Cancellable;
 import org.bukkit.event.HandlerList;
 import org.jetbrains.annotations.NotNull;
 
 /**
- * Called when a player enters their wardrobe
+ * Called when a player enters their {@link Wardrobe}.
  */
 public class PlayerWardrobeEnterEvent extends PlayerCosmeticEvent implements Cancellable {
-    private static final HandlerList handlers = new HandlerList();
+    private static final HandlerList HANDLER_LIST = new HandlerList();
+
     private boolean cancel = false;
-    @Getter @Setter
+
     private Wardrobe wardrobe;
 
     public PlayerWardrobeEnterEvent(@NotNull CosmeticUser who, @NotNull Wardrobe wardrobe) {
@@ -22,33 +21,38 @@ public class PlayerWardrobeEnterEvent extends PlayerCosmeticEvent implements Can
         this.wardrobe = wardrobe;
     }
 
+    /**
+     * Get the {@link Wardrobe} the player is entering.
+     * @return The wardrobe being entered
+     */
+    public Wardrobe getWardrobe() {
+        return wardrobe;
+    }
+
+    /**
+     * Set the {@link Wardrobe} the player is entering.
+     * @param wardrobe the wardrobe being entered
+     */
+    public void setWardrobe(Wardrobe wardrobe) {
+        this.wardrobe = wardrobe;
+    }
+
     @Override
     public boolean isCancelled() {
         return cancel;
     }
 
-    /**
-     * Sets the cancellation state of this event
-     *
-     * <p>
-     * Canceling this event will prevent the player from entering their wardrobe
-     * </p>
-     *
-     * @param cancel true if you wish to cancel this event
-     */
     @Override
     public void setCancelled(boolean cancel) {
         this.cancel = cancel;
     }
 
     @Override
-    @NotNull
-    public HandlerList getHandlers() {
-        return handlers;
+    public @NotNull HandlerList getHandlers() {
+        return HANDLER_LIST;
     }
 
-    @NotNull
-    public static HandlerList getHandlerList() {
-        return handlers;
+    public static @NotNull HandlerList getHandlerList() {
+        return HANDLER_LIST;
     }
 }

common/src/main/java/com/hibiscusmc/hmccosmetics/api/events/PlayerWardrobeLeaveEvent.java

@@ -6,10 +6,11 @@ import org.bukkit.event.HandlerList;
 import org.jetbrains.annotations.NotNull;
 
 /**
- * Called when a player leaves their wardrobe
+ * Called when a player leaves their {@link com.hibiscusmc.hmccosmetics.config.Wardrobe}.
  */
 public class PlayerWardrobeLeaveEvent extends PlayerCosmeticEvent implements Cancellable {
-    private static final HandlerList handlers = new HandlerList();
+    private static final HandlerList HANDLER_LIST = new HandlerList();
+
     private boolean cancel = false;
 
     public PlayerWardrobeLeaveEvent(@NotNull CosmeticUser who) {
@@ -21,28 +22,17 @@ public class PlayerWardrobeLeaveEvent extends PlayerCosmeticEvent implements Can
         return cancel;
     }
 
-    /**
-     * Sets the cancellation state of this event
-     *
-     * <p>
-     * Canceling this event will prevent the player from leaving their wardrobe
-     * </p>
-     *
-     * @param cancel true if you wish to cancel this event
-     */
     @Override
     public void setCancelled(boolean cancel) {
         this.cancel = cancel;
     }
 
     @Override
-    @NotNull
-    public HandlerList getHandlers() {
-        return handlers;
+    public @NotNull HandlerList getHandlers() {
+        return HANDLER_LIST;
     }
 
-    @NotNull
-    public static HandlerList getHandlerList() {
-        return handlers;
+    public static @NotNull HandlerList getHandlerList() {
+        return HANDLER_LIST;
     }
 }