From 2ea272ee4a39a62dfed0e731fc2d58210062eccf Mon Sep 17 00:00:00 2001
From: Craftinators <craftinatorssx@gmail.com>
Date: Thu, 16 Mar 2023 17:39:58 -0400
Subject: [PATCH] fix(Hook): abstraction and documentation of `Hook`

---
 .../hibiscusmc/hmccosmetics/hooks/Hook.java   | 85 ++++++++++++++-----
 1 file changed, 66 insertions(+), 19 deletions(-)

diff --git a/common/src/main/java/com/hibiscusmc/hmccosmetics/hooks/Hook.java b/common/src/main/java/com/hibiscusmc/hmccosmetics/hooks/Hook.java
index 5757c8b1..b263f0df 100644
--- a/common/src/main/java/com/hibiscusmc/hmccosmetics/hooks/Hook.java
+++ b/common/src/main/java/com/hibiscusmc/hmccosmetics/hooks/Hook.java
@@ -2,45 +2,92 @@ package com.hibiscusmc.hmccosmetics.hooks;
 
 import org.bukkit.event.Listener;
 import org.bukkit.inventory.ItemStack;
+import org.jetbrains.annotations.NotNull;
+import org.jetbrains.annotations.Nullable;
 
-public class Hook implements Listener {
-
+/**
+ * Represents a hook into other minecraft plugins
+ */
+public abstract class Hook implements Listener {
     private final String id;
-    private boolean active;
-    private boolean itemHook;
+    private boolean active = false;
+    private boolean itemHook = false;
 
-    public Hook(String id) {
+    public Hook(@NotNull String id) {
         this.id = id;
-        active = false;
         Hooks.addHook(this);
     }
 
-    public void load() {
-        // Override
-    }
+    /**
+     * Loads this hook
+     *
+     * @implNote By default, this method does nothing. It should be overridden by child classes to implement any necessary loading logic
+     */
+    public void load() { }
 
-    public ItemStack getItem(String itemId) {
+    /**
+     * Gets an {@link ItemStack} that is associated with the provided id from the hooked plugin
+     * @param itemId The id of the {@link ItemStack}
+     * @return The {@link ItemStack} with the id provided. If an invalid id was provided or if the hook doesn't have any related {@link ItemStack}s then this will return null
+     * @implNote By default, this method returns null. It should be overridden by child classes if you will to have your hook return a related {@link ItemStack}
+     */
+    @Nullable
+    public ItemStack getItem(@NotNull String itemId) {
         return null;
-        // Override
     }
 
-    public String getId() {
+    /**
+     * Gets the id of this hook
+     *
+     * @return The unique id for this hook
+     */
+    @NotNull
+    public final String getId() {
         return id;
     }
 
-    public void setActive(boolean active) {
-        this.active = active;
-    }
-
+    /**
+     * Gets whether this hook has been activated
+     * @return true if this hook is active, false otherwise
+     * @deprecated As of release 2.2.5+, replaced by {@link #isActive()}
+     */
+    @Deprecated
     public boolean getActive() {
         return this.active;
     }
 
-    public void setEnabledItemHook(boolean enabled) {
-        itemHook = enabled;
+    /**
+     * Gets whether this hook has been activated
+     * @return true if this hook is active, false otherwise
+     * @since 2.2.5
+     */
+    public final boolean isActive() {
+        return this.active;
     }
 
-    public boolean hasEnabledItemHook() {
+    /**
+     * Sets whether this hook is active
+     * @param active true to activate the hook, false otherwise
+     */
+    public final void setActive(boolean active) {
+        this.active = active;
+    }
+
+    /**
+     * Whether the method {@link #getItem(String)} should return a non-null value
+     * @return true if {@link #getItem(String)} should return a non-null value, false otherwise
+     *
+     * @apiNote Even though this method returns true does not mean that {@link #getItem(String)} won't return null, rather if this returns false then {@link #getItem(String)} should return false everytime
+     */
+    public final boolean hasEnabledItemHook() {
         return itemHook;
     }
+
+    /**
+     * Sets whether the method {@link #getItem(String)} should return a non-null value
+     * @param enabled true if {@link #getItem(String)} should return a non-null value, false otherwise
+     */
+    public final void setEnabledItemHook(boolean enabled) {
+        itemHook = enabled;
+    }
 }