chore: code documentation and comments

Thatsmusic99 · Thatsmusic99 · commit 435d1dcd6601 · 2023-02-17T09:32:39.000Z
diff --git a/src/main/java/io/github/thatsmusic99/headsplus/api/HPPlayer.java b/src/main/java/io/github/thatsmusic99/headsplus/api/HPPlayer.java
@@ -15,6 +15,8 @@
 import org.bukkit.OfflinePlayer;
 import org.bukkit.entity.Player;
 import org.bukkit.scheduler.BukkitRunnable;
+import org.jetbrains.annotations.NotNull;
+import org.jetbrains.annotations.Nullable;
 
 import java.util.ArrayList;
 import java.util.HashMap;
@@ -97,9 +99,16 @@ public static CompletableFuture<HPPlayer> getHPPlayerAsync(UUID uuid) {
         return CompletableFuture.supplyAsync(() -> new HPPlayer(uuid), HeadsPlus.async);
     }
 
-    public CompletableFuture<Void> addCompleteChallenge(Challenge c) {
-        completeChallenges.add(c.getConfigName());
-        return ChallengeSQLManager.get().completeChallenge(uuid, c.getConfigName(), true);
+    /**
+     * Completes a specified challenge for a specific player.
+     *
+     * @param challenge The challenge in question.
+     * @return a completable future covering this action.
+     */
+
+    public CompletableFuture<Void> addCompleteChallenge(Challenge challenge) {
+        completeChallenges.add(challenge.getConfigName());
+        return ChallengeSQLManager.get().completeChallenge(uuid, challenge.getConfigName(), true);
     }
 
     public void addXp(long xp) {
diff --git a/src/main/java/io/github/thatsmusic99/headsplus/api/Level.java b/src/main/java/io/github/thatsmusic99/headsplus/api/Level.java
@@ -1,5 +1,8 @@
 package io.github.thatsmusic99.headsplus.api;
 
+/**
+ * Represents a level. This is a cosmetic feature that players can aim for.
+ */
 public class Level {
 
     private final String configName;
diff --git a/src/main/java/io/github/thatsmusic99/headsplus/listeners/LeaderboardListeners.java b/src/main/java/io/github/thatsmusic99/headsplus/listeners/LeaderboardListeners.java
@@ -109,9 +109,19 @@ private static class HeadCraftListener extends HeadsPlusListener<HeadCraftEvent>
         @Override
         public void onEvent(HeadCraftEvent event) {
             Player player = event.getPlayer();
+
+            // If the player can gain XP...
             if (RestrictionsManager.canUse(player.getWorld().getName(), RestrictionsManager.ActionType.XP_GAINS)) {
+
+                // The key of the XP
                 String key = "recipes." + event.getType().substring(event.getType().indexOf("_") + 1);
-                HPPlayer.getHPPlayer(player.getUniqueId()).addXp(ConfigCrafting.get().getCraftingXp(key) * event.getHeadsCrafted());
+
+                // Calculate the XP added
+                long xp = ConfigCrafting.get().getCraftingXp(key) * event.getHeadsCrafted();
+
+                // Add the crafting XP
+                HPPlayer.getHPPlayerAsync(player.getUniqueId()).thenAcceptAsync(hpPlayer ->
+                        hpPlayer.addXp(xp), HeadsPlus.sync);
             }
             if (!MainConfig.get().getMainFeatures().LEADERBOARDS || event.getType() == null) return;
             if (event.getType().equalsIgnoreCase("invalid") || event.getType().isEmpty()) return;
diff --git a/src/main/java/io/github/thatsmusic99/headsplus/managers/MaskManager.java b/src/main/java/io/github/thatsmusic99/headsplus/managers/MaskManager.java
@@ -10,10 +10,18 @@
 import org.bukkit.potion.PotionEffect;
 import org.bukkit.potion.PotionEffectType;
 import org.bukkit.scheduler.BukkitRunnable;
+import org.jetbrains.annotations.NotNull;
+import org.jetbrains.annotations.Nullable;
 
 import java.util.*;
 import java.util.concurrent.CompletableFuture;
 
+/**
+ * The manager that takes care of masks. Masks are heads that when worn, give players certain effects. This manager
+ * allows external plugins to access and register their own masks.
+ *
+ * @author Thatsmusic99 (Holly)
+ */
 public class MaskManager {
 
     private final HashMap<String, MaskInfo> masks = new HashMap<>();
@@ -25,54 +33,120 @@ private MaskManager(boolean empty) {
         if (!empty) init();
     }
 
+    /**
+     * Initiates the mask manager. Not intended for external use.
+     */
     public MaskManager() {
         this(false);
     }
 
+    /**
+     * Retrieves an instance of the Mask Manager. If an instance does not already exist, one will be created.
+     *
+     * @return the existing instance of the mask manager.
+     */
+    @NotNull
     public static MaskManager get() {
         if (instance == null) instance = new MaskManager(true);
         return instance;
     }
 
+    /**
+     * The method used to re-register masks in the configuration file. Any head added via an API will be lost.
+     */
     public void reload() {
         reset();
         init();
     }
 
-    public void resetMask(Player player) {
+    /**
+     * Removes the mask effects from a specific player.
+     *
+     * @param player the player to have the mask effects reset.
+     */
+    public void resetMask(@NotNull Player player) {
+        Objects.requireNonNull(player, "The player specified is null!");
+
+        // If the player does not have an active mask, stop there.
         if (!runningTasks.containsKey(player.getUniqueId().toString())) return;
+
+        // Cancel the runnable controlling the masks.
         runningTasks.get(player.getUniqueId().toString()).cancel();
     }
 
+    /**
+     * Clears all registered masks and stops all running ones.
+     */
     public void reset() {
         masks.clear();
         runningTasks.values().forEach(BukkitRunnable::cancel);
         runningTasks.clear();
     }
 
-    public void registerMask(String key, MaskInfo headInfo) {
-        masks.put(key, headInfo);
+    /**
+     * Registers a mask with an ID and its mask data.
+     *
+     * @param key The ID of the mask to be specified. It does not require the HPM# prefix.
+     * @param maskInfo The mask data in question.
+     * @throws IllegalStateException if the mask with the specific ID has already been registered.
+     */
+    public void registerMask(@NotNull String key, @NotNull MaskInfo maskInfo) {
+
+        // Make sure nothing is null
+        Objects.requireNonNull(key, "The key to be used is null!");
+        Objects.requireNonNull(maskInfo, "The mask data is null!");
+
+        // If the key includes HPM#, remove it.
+        key = removeMaskPrefix(key);
+
+        // If the mask has already been registered, stop it there
+        if (isMaskRegistered(key)) {
+            throw new IllegalStateException("The mask " + key + " has already been registered!");
+        }
+
+        // Register the mask!
+        masks.put(key, maskInfo);
     }
 
-    public MaskInfo getMaskInfo(String key) {
-        if (key.startsWith("HPM#")) {
-            key = key.substring(4);
-        }
-        return (MaskInfo) masks.getOrDefault(key, new MaskInfo()).clone();
+    /**
+     * Gets the mask data of a mask with a specific ID. The mask data in question is cloned, so it is used per-player.
+     *
+     * @param key The ID of the mask. It can contain the HPM# prefix, but HP# will potentially return null.
+     * @return The mask data of the mask if it is registered. If it is not registered, then null is returned instead.
+     */
+    @Nullable
+    public MaskInfo getMaskInfo(@NotNull String key) {
+
+        // Make sure nothing is null
+        Objects.requireNonNull(key, "The key used to search for a mask is null!");
+
+        // Get the mask information with the specified character.
+        MaskInfo info = masks.get(removeMaskPrefix(key));
+        if (info == null) return null;
+        return (MaskInfo) info.clone();
     }
 
+    /**
+     * Determines whether a mask with a specified ID is registered.
+     *
+     * @param key The key of the mask to be checked.
+     * @return true if the mask is registered, false if it is not.
+     */
     public boolean isMaskRegistered(String key) {
-        if (key.startsWith("HPM#")) {
-            key = key.substring(4);
-        }
-        return masks.containsKey(key);
+        return masks.containsKey(removeMaskPrefix(key));
     }
 
+    /**
+     * A set of all masks that have been registered. The set in question is cloned, so modifying it has no effect on the
+     * actual masks map.
+     *
+     * @return A set of all mask IDs.
+     */
     public Set<String> getMaskKeys() {
-        return masks.keySet();
+        return new HashSet<>(masks.keySet());
     }
 
-    public void init() {
+    private void init() {
         ConfigMasks masksConfig = ConfigMasks.get();
         // Get the config section
         ConfigSection masksSection = masksConfig.getConfigSection("masks");
@@ -125,14 +199,34 @@ public void init() {
         HeadsPlus.get().getLogger().info("Registered " + masks.size() + " masks.");
     }
 
+    private String removeMaskPrefix(String key) {
+        if (key.startsWith("HPM#")) {
+            key = key.substring(4);
+        }
+        return key;
+    }
+
+    /**
+     * A base class representing masks. It inherits {@link HeadManager.HeadInfo}, so item metadata is stored there.
+     * Actual mask functions are handled within this class.
+     */
     public static class MaskInfo extends HeadManager.HeadInfo {
 
         protected String id;
 
+        /**
+         * Initialises an empty mask without an ID.
+         */
         public MaskInfo() {
             super();
         }
 
+        /**
+         * Initialises a mask with existing head info, and its own ID.
+         *
+         * @param info The head info to be adopted by the mask.
+         * @param id The ID for the head.
+         */
         public MaskInfo(HeadManager.HeadInfo info, String id) {
             super();
             this.id = id;
@@ -142,7 +236,33 @@ public MaskInfo(HeadManager.HeadInfo info, String id) {
             withMaterial(info.getMaterial());
         }
 
-        public void run(Player player) {
+        /**
+         * Prompts the mask functions to start with a specified player.
+         *
+         * @param player The player using the mask.
+         */
+        public void run(@NotNull Player player) {
+        }
+
+        /**
+         * Determines whether a specified player is still wearing the mask and is able to.
+         *
+         * @param player The player in question
+         * @return true if the mask effects can persist, or false if the player isn't wearing the mask, or if the
+         * effects should not apply.
+         */
+        public boolean isMaskBeingWorn(@Nullable Player player) {
+            // If the player is null, offline or if masks are disabled, stop there
+            if (player == null || !player.isOnline() || !MainConfig.get().getMainFeatures().MASKS) {
+                return false;
+            }
+            // Get the helmet and ensure it is a valid mask
+            ItemStack helmet = player.getInventory().getHelmet();
+            if (helmet == null || !PersistenceManager.get().getMaskType(helmet).equals(id)) {
+                return false;
+            }
+            // Make sure WorldGuard is not blocking effects
+            return !HeadsPlus.get().canUseWG() || FlagHandler.canUseMasks(player);
         }
 
         @Override
@@ -167,6 +287,9 @@ public ItemStack forceBuildHead() {
         }
     }
 
+    /**
+     * Represents a mask that applies potion effects to a player when worn.
+     */
     public class PotionMask extends MaskInfo {
 
         private List<PotionEffect> effects;
@@ -187,24 +310,15 @@ public PotionMask addEffect(PotionEffect effect) {
         }
 
         @Override
-        public void run(Player player) {
+        public void run(@NotNull Player player) {
             BukkitRunnable runnable = new BukkitRunnable() {
 
                 private int intervals = MainConfig.get().getMasks().RESET_INTERVAL - 1;
 
                 @Override
                 public void run() {
-                    if (player == null || !player.isOnline() || !MainConfig.get().getMainFeatures().MASKS) {
-                        cancel();
-                        return;
-                    }
-                    // Get the helmet
-                    ItemStack helmet = player.getInventory().getHelmet();
-                    if (helmet == null || !PersistenceManager.get().getMaskType(helmet).equals(id)) {
-                        cancel();
-                        return;
-                    }
-                    if (HeadsPlus.get().canUseWG() && !FlagHandler.canUseMasks(player)) {
+                    // If the mask isn't being worn, stop there and cancel the mask
+                    if (!isMaskBeingWorn(player)) {
                         cancel();
                         return;
                     }
