Adds comments to all custom events

Adds full comments to every class implementing StarGateEvent
Adds another abstract event StargatePlayerEvent which reduces code duplication

src/main/java/net/knarcraft/stargate/event/StargateAccessEvent.java

@@ -3,24 +3,18 @@ package net.knarcraft.stargate.event;
 import net.knarcraft.stargate.Portal;
 import org.bukkit.entity.Player;
 import org.bukkit.event.HandlerList;
+import org.jetbrains.annotations.NotNull;
 
+/**
+ * This event should be called whenever a player attempts to access a stargate
+ */
 @SuppressWarnings("unused")
-public class StargateAccessEvent extends StargateEvent {
+public class StargateAccessEvent extends StargatePlayerEvent {
 
-	private final Player player;
 	private boolean deny;
 	
 	private static final HandlerList handlers = new HandlerList();
 
-
-    /**
-     * Gets a handler-list containing all event handlers
-     * @return <p>A handler-list with all event handlers</p>
-     */
-	public static HandlerList getHandlerList() {
-		return handlers;
-	}
-
     /**
      * Instantiates a new stargate access event
      * @param player <p>The player involved in the vent</p>
@@ -28,9 +22,8 @@ public class StargateAccessEvent extends StargateEvent {
      * @param deny <p>Whether the event should be denied</p>
      */
 	public StargateAccessEvent(Player player, Portal portal, boolean deny) {
-		super("StargateAccessEvent", portal);
+		super("StargateAccessEvent", portal, player);
 
-		this.player = player;
 		this.deny = deny;
 	}
 
@@ -51,15 +44,17 @@ public class StargateAccessEvent extends StargateEvent {
 	}
 
     /**
-     * Gets the player involved in this stargate access event
-     * @return <p>The player involved in this event</p>
+     * Gets a handler-list containing all event handlers
+     * @return <p>A handler-list with all event handlers</p>
      */
-	public Player getPlayer() {
-		return this.player;
-	}
-
-    @Override
-    public @org.jetbrains.annotations.NotNull HandlerList getHandlers() {
+    public static HandlerList getHandlerList() {
         return handlers;
     }
+
+    @Override
+    @NotNull
+    public HandlerList getHandlers() {
+        return handlers;
+    }
+
 }

src/main/java/net/knarcraft/stargate/event/StargateActivateEvent.java

@@ -5,51 +5,84 @@ import org.bukkit.entity.Player;
 import org.bukkit.event.HandlerList;
 import org.jetbrains.annotations.NotNull;
 
-import java.util.ArrayList;
+import java.util.List;
 
-public class StargateActivateEvent extends StargateEvent {
+/**
+ * This event should be called whenever a player activates a stargate
+ * <p>Activation of a stargate happens when a player right-clicks the sign of a stargate.</p>
+ */
+@SuppressWarnings("unused")
+public class StargateActivateEvent extends StargatePlayerEvent {
 
-    private final Player player;
-    private ArrayList<String> destinations;
+    private List<String> destinations;
     private String destination;
 
     private static final HandlerList handlers = new HandlerList();
 
+    /**
+     * Instantiates a new stargate activate event
+     *
+     * @param portal       <p>The activated portal</p>
+     * @param player       <p>The player activating the portal</p>
+     * @param destinations <p>The destinations available to the player using the portal</p>
+     * @param destination  <p>The chosen destination to activate</p>
+     */
+    public StargateActivateEvent(Portal portal, Player player, List<String> destinations, String destination) {
+        super("StargatActivateEvent", portal, player);
+
+        this.destinations = destinations;
+        this.destination = destination;
+    }
+
+    /**
+     * Gets the destinations available for the portal
+     *
+     * @return <p>The destinations available for the portal</p>
+     */
+    public List<String> getDestinations() {
+        return destinations;
+    }
+
+    /**
+     * Sets the destinations available to the player using the portal
+     *
+     * @param destinations <p>The new list of available destinations</p>
+     */
+    public void setDestinations(List<String> destinations) {
+        this.destinations = destinations;
+    }
+
+    /**
+     * Gets the chosen destination to activate
+     *
+     * @return <p>The chosen destination to activate</p>
+     */
+    public String getDestination() {
+        return destination;
+    }
+
+    /**
+     * Sets (changes) the chosen destination to activate
+     *
+     * @param destination <p>The new destination to activate</p>
+     */
+    public void setDestination(String destination) {
+        this.destination = destination;
+    }
+
+    /**
+     * Gets a handler-list containing all event handlers
+     *
+     * @return <p>A handler-list with all event handlers</p>
+     */
+    public static HandlerList getHandlerList() {
+        return handlers;
+    }
+
+    @Override
     @NotNull
     public HandlerList getHandlers() {
         return handlers;
     }
 
-    public static HandlerList getHandlerList() {
-        return handlers;
-    }
-
-    public StargateActivateEvent(Portal portal, Player player, ArrayList<String> destinations, String destination) {
-        super("StargatActivateEvent", portal);
-
-        this.player = player;
-        this.destinations = destinations;
-        this.destination = destination;
-    }
-
-    public Player getPlayer() {
-        return player;
-    }
-
-    public ArrayList<String> getDestinations() {
-        return destinations;
-    }
-
-    public void setDestinations(ArrayList<String> destinations) {
-        this.destinations = destinations;
-    }
-
-    public String getDestination() {
-        return destination;
-    }
-
-    public void setDestination(String destination) {
-        this.destination = destination;
-    }
-
 }

src/main/java/net/knarcraft/stargate/event/StargateCloseEvent.java

@@ -4,33 +4,59 @@ import net.knarcraft.stargate.Portal;
 import org.bukkit.event.HandlerList;
 import org.jetbrains.annotations.NotNull;
 
+/**
+ * This event should be called whenever a stargate is closed
+ */
+@SuppressWarnings("unused")
 public class StargateCloseEvent extends StargateEvent {
 
     private boolean force;
 
     private static final HandlerList handlers = new HandlerList();
 
-    @NotNull
-    public HandlerList getHandlers() {
-        return handlers;
-    }
-
-    public static HandlerList getHandlerList() {
-        return handlers;
-    }
-
+    /**
+     * Instantiates a new stargate closing event
+     *
+     * @param portal <p>The portal to close</p>
+     * @param force  <p>Whether to force the gate to close, even if set as always-on</p>
+     */
     public StargateCloseEvent(Portal portal, boolean force) {
         super("StargateCloseEvent", portal);
 
         this.force = force;
     }
 
+    /**
+     * Gets whether to force the stargate to close
+     *
+     * @return <p>Whether to force the stargate to close</p>
+     */
     public boolean getForce() {
         return force;
     }
 
+    /**
+     * Sets whether the stargate should be forced to close
+     *
+     * @param force <p>Whether the stargate should be forced to close</p>
+     */
     public void setForce(boolean force) {
         this.force = force;
     }
 
+    /**
+     * Gets a handler-list containing all event handlers
+     *
+     * @return <p>A handler-list with all event handlers</p>
+     */
+    public static HandlerList getHandlerList() {
+        return handlers;
+    }
+
+    @NotNull
+    @Override
+    public HandlerList getHandlers() {
+        return handlers;
+    }
+
 }

src/main/java/net/knarcraft/stargate/event/StargateCreateEvent.java

@@ -5,9 +5,12 @@ import org.bukkit.entity.Player;
 import org.bukkit.event.HandlerList;
 import org.jetbrains.annotations.NotNull;
 
-public class StargateCreateEvent extends StargateEvent {
+/**
+ * This event should be called whenever a stargate is created
+ */
+@SuppressWarnings("unused")
+public class StargateCreateEvent extends StargatePlayerEvent {
 
-    private final Player player;
     private boolean deny;
     private String denyReason;
     private final String[] lines;
@@ -15,54 +18,102 @@ public class StargateCreateEvent extends StargateEvent {
 
     private static final HandlerList handlers = new HandlerList();
 
-    @NotNull
-    public HandlerList getHandlers() {
-        return handlers;
-    }
-
-    public static HandlerList getHandlerList() {
-        return handlers;
-    }
-
+    /**
+     * Instantiates a new stargate creation event
+     *
+     * @param player     <p>Thg player creating the stargate</p>
+     * @param portal     <p>The created portal</p>
+     * @param lines      <p>The lines of the sign creating the star gate</p>
+     * @param deny       <p>Whether to deny the creation of the new gate</p>
+     * @param denyReason <p>The reason stargate creation was denied</p>
+     * @param cost       <p>The cost of creating the new star gate</p>
+     */
     public StargateCreateEvent(Player player, Portal portal, String[] lines, boolean deny, String denyReason, int cost) {
-        super("StargateCreateEvent", portal);
-        this.player = player;
+        super("StargateCreateEvent", portal, player);
         this.lines = lines;
         this.deny = deny;
         this.denyReason = denyReason;
         this.cost = cost;
     }
 
-    public Player getPlayer() {
-        return player;
-    }
-
+    /**
+     * Gets a given line from the sign creating the star gate
+     *
+     * @param index <p>The line number to get</p>
+     * @return <p>The text on the given line</p>
+     * @throws IndexOutOfBoundsException <p>If given a line index less than zero or above three</p>
+     */
     public String getLine(int index) throws IndexOutOfBoundsException {
         return lines[index];
     }
 
+    /**
+     * Gets whether the stargate creation should be denied
+     *
+     * @return <p>Whether the stargate creation should be denied</p>
+     */
     public boolean getDeny() {
         return deny;
     }
 
+    /**
+     * Sets whether the stargate creation should be denied
+     *
+     * @param deny <p>Whether the stargate creation should be denied</p>
+     */
     public void setDeny(boolean deny) {
         this.deny = deny;
     }
 
+    /**
+     * Gets the reason the stargate creation was denied
+     *
+     * @return <p>The reason the stargate creation was denied</p>
+     */
     public String getDenyReason() {
         return denyReason;
     }
 
+    /**
+     * Sets the reason the stargate creation was denied
+     *
+     * @param denyReason <p>The new reason why the stargate creation was denied</p>
+     */
     public void setDenyReason(String denyReason) {
         this.denyReason = denyReason;
     }
 
+    /**
+     * Gets the cost of creating the stargate
+     *
+     * @return <p>The cost of creating the stargate</p>
+     */
     public int getCost() {
         return cost;
     }
 
+    /**
+     * Sets the cost of creating the stargate
+     *
+     * @param cost <p>The new cost of creating the stargate</p>
+     */
     public void setCost(int cost) {
         this.cost = cost;
     }
 
+    /**
+     * Gets a handler-list containing all event handlers
+     *
+     * @return <p>A handler-list with all event handlers</p>
+     */
+    public static HandlerList getHandlerList() {
+        return handlers;
+    }
+
+    @NotNull
+    @Override
+    public HandlerList getHandlers() {
+        return handlers;
+    }
+
 }

src/main/java/net/knarcraft/stargate/event/StargateDeactivateEvent.java

@@ -4,21 +4,37 @@ import net.knarcraft.stargate.Portal;
 import org.bukkit.event.HandlerList;
 import org.jetbrains.annotations.NotNull;
 
+/**
+ * This event should be called whenever a stargate is deactivated
+ * <p>A deactivation is usually caused by no activity for a set amount of time.</p>
+ */
+@SuppressWarnings("unused")
 public class StargateDeactivateEvent extends StargateEvent {
 
     private static final HandlerList handlers = new HandlerList();
 
-    @NotNull
-    public HandlerList getHandlers() {
-        return handlers;
+    /**
+     * Instantiates a new stargate deactivation event
+     *
+     * @param portal <p>The portal which was deactivated</p>
+     */
+    public StargateDeactivateEvent(Portal portal) {
+        super("StargatDeactivateEvent", portal);
     }
 
+    /**
+     * Gets a handler-list containing all event handlers
+     *
+     * @return <p>A handler-list with all event handlers</p>
+     */
     public static HandlerList getHandlerList() {
         return handlers;
     }
 
-    public StargateDeactivateEvent(Portal portal) {
-        super("StargatDeactivateEvent", portal);
-
+    @NotNull
+    @Override
+    public HandlerList getHandlers() {
+        return handlers;
     }
+
 }

src/main/java/net/knarcraft/stargate/event/StargateDestroyEvent.java

@@ -8,28 +8,15 @@ import org.jetbrains.annotations.NotNull;
 /**
  * This event represents an event where a star gate is destroyed or attempted to be destroyed
  */
-public class StargateDestroyEvent extends StargateEvent {
+@SuppressWarnings("unused")
+public class StargateDestroyEvent extends StargatePlayerEvent {
 
-    private final Player player;
     private boolean deny;
     private String denyReason;
     private int cost;
 
     private static final HandlerList handlers = new HandlerList();
 
-    @NotNull
-    public HandlerList getHandlers() {
-        return handlers;
-    }
-
-    /**
-     * Gets a handler-list containing all event handlers
-     * @return <p>A handler-list with all event handlers</p>
-     */
-    public static HandlerList getHandlerList() {
-        return handlers;
-    }
-
     /**
      * Instantiates a new Stargate Destroy Event
      * @param portal <p>The portal destroyed</p>
@@ -39,21 +26,12 @@ public class StargateDestroyEvent extends StargateEvent {
      * @param cost <p>The cost of destroying the portal</p>
      */
     public StargateDestroyEvent(Portal portal, Player player, boolean deny, String denyMsg, int cost) {
-        super("StargateDestroyEvent", portal);
-        this.player = player;
+        super("StargateDestroyEvent", portal, player);
         this.deny = deny;
         this.denyReason = denyMsg;
         this.cost = cost;
     }
 
-    /**
-     * Gets the player causing the destroy event
-     * @return <p>The player causing the destroy event</p>
-     */
-    public Player getPlayer() {
-        return player;
-    }
-
     /**
      * Gets whether this event should be denied
      * @return <p>Whether this event should be denied</p>
@@ -102,4 +80,19 @@ public class StargateDestroyEvent extends StargateEvent {
         this.cost = cost;
     }
 
+    /**
+     * Gets a handler-list containing all event handlers
+     *
+     * @return <p>A handler-list with all event handlers</p>
+     */
+    public static HandlerList getHandlerList() {
+        return handlers;
+    }
+
+    @NotNull
+    @Override
+    public HandlerList getHandlers() {
+        return handlers;
+    }
+
 }

src/main/java/net/knarcraft/stargate/event/StargateEvent.java

@@ -10,15 +10,23 @@ import org.bukkit.event.Event;
 @SuppressWarnings("unused")
 public abstract class StargateEvent extends Event implements Cancellable {
 
-    protected final Portal portal;
-    protected boolean cancelled;
+    private final Portal portal;
+    private boolean cancelled;
 
-    public StargateEvent(String event, Portal portal) {
+    /**
+     * Instantiates a new stargate event
+     * @param event <p>UNUSED</p>
+     * @param portal <p>The portal involved in this stargate event</p>
+     */
+    StargateEvent(String event, Portal portal) {
         this.portal = portal;
         this.cancelled = false;
     }
 
-
+    /**
+     * Gets the portal involved in this stargate event
+     * @return <p>The portal involved in this stargate event</p>
+     */
     public Portal getPortal() {
         return portal;
     }

src/main/java/net/knarcraft/stargate/event/StargateOpenEvent.java

@@ -5,44 +5,55 @@ import org.bukkit.entity.Player;
 import org.bukkit.event.HandlerList;
 import org.jetbrains.annotations.NotNull;
 
-public class StargateOpenEvent extends StargateEvent {
+/**
+ * This event should be called whenever a player opens a stargate
+ */
+public class StargateOpenEvent extends StargatePlayerEvent {
 
-    private final Player player;
     private boolean force;
 
     private static final HandlerList handlers = new HandlerList();
 
+    /**
+     * Instantiates a new stargate open event
+     * @param player <p>The player opening the stargate</p>
+     * @param portal <p>The portal opened</p>
+     * @param force <p>Whether to force the portal open</p>
+     */
+    public StargateOpenEvent(Player player, Portal portal, boolean force) {
+        super("StargateOpenEvent", portal, player);
+
+        this.force = force;
+    }
+
+    /**
+     * Gets whether the portal should be forced open
+     * @return <p>Whether the portal should be forced open</p>
+     */
+    public boolean getForce() {
+        return force;
+    }
+
+    /**
+     * Sets whether the portal should be forced open
+     * @param force <p>Whether the portal should be forced open</p>
+     */
+    public void setForce(boolean force) {
+        this.force = force;
+    }
+
+    /**
+     * Gets a handler-list containing all event handlers
+     * @return <p>A handler-list with all event handlers</p>
+     */
+    public static HandlerList getHandlerList() {
+        return handlers;
+    }
+
+    @Override
     @NotNull
     public HandlerList getHandlers() {
         return handlers;
     }
 
-    public static HandlerList getHandlerList() {
-        return handlers;
-    }
-
-    public StargateOpenEvent(Player player, Portal portal, boolean force) {
-        super("StargateOpenEvent", portal);
-
-        this.player = player;
-        this.force = force;
-    }
-
-    /**
-     * Return the player than opened the gate.
-     *
-     * @return player than opened the gate
-     */
-    public Player getPlayer() {
-        return player;
-    }
-
-    public boolean getForce() {
-        return force;
-    }
-
-    public void setForce(boolean force) {
-        this.force = force;
-    }
-
 }

src/main/java/net/knarcraft/stargate/event/StargatePlayerEvent.java

@@ -0,0 +1,33 @@
+package net.knarcraft.stargate.event;
+
+import net.knarcraft.stargate.Portal;
+import org.bukkit.entity.Player;
+
+/**
+ * An abstract event describing any stargate event where a player is involved
+ */
+public abstract class StargatePlayerEvent extends StargateEvent {
+
+    private final Player player;
+
+    /**
+     * Instantiates a new stargate player event
+     *
+     * @param event  <p>UNUSED</p>
+     * @param portal <p>The portal involved in this stargate event</p>
+     */
+    StargatePlayerEvent(String event, Portal portal, Player player) {
+        super(event, portal);
+        this.player = player;
+    }
+
+    /**
+     * Gets the player creating the star gate
+     *
+     * @return <p>The player creating the star gate</p>
+     */
+    public Player getPlayer() {
+        return player;
+    }
+
+}

src/main/java/net/knarcraft/stargate/event/StargatePortalEvent.java

@@ -6,38 +6,29 @@ import org.bukkit.entity.Player;
 import org.bukkit.event.HandlerList;
 import org.jetbrains.annotations.NotNull;
 
-public class StargatePortalEvent extends StargateEvent {
+/**
+ * This event should be called whenever a player teleports through a stargate
+ */
+@SuppressWarnings("unused")
+public class StargatePortalEvent extends StargatePlayerEvent {
 
-    private final Player player;
     private final Portal destination;
     private Location exit;
 
     private static final HandlerList handlers = new HandlerList();
 
-    @NotNull
-    public HandlerList getHandlers() {
-        return handlers;
-    }
-
-    public static HandlerList getHandlerList() {
-        return handlers;
-    }
-
-    public StargatePortalEvent(Player player, Portal portal, Portal dest, Location exit) {
-        super("StargatePortalEvent", portal);
-
-        this.player = player;
-        this.destination = dest;
-        this.exit = exit;
-    }
-
     /**
-     * Return the player that went through the gate.
-     *
-     * @return player that went through the gate
+     * Instantiates a new stargate portal event
+     * @param player <p>The player teleporting</p>
+     * @param portal <p>The portal the player entered from</p>
+     * @param destination <p>The destination the player should exit from</p>
+     * @param exit <p>The exit location of the destination portal the user will be teleported to</p>
      */
-    public Player getPlayer() {
-        return player;
+    public StargatePortalEvent(Player player, Portal portal, Portal destination, Location exit) {
+        super("StargatePortalEvent", portal, player);
+
+        this.destination = destination;
+        this.exit = exit;
     }
 
     /**
@@ -65,4 +56,18 @@ public class StargatePortalEvent extends StargateEvent {
         this.exit = loc;
     }
 
+    /**
+     * Gets a handler-list containing all event handlers
+     * @return <p>A handler-list with all event handlers</p>
+     */
+    public static HandlerList getHandlerList() {
+        return handlers;
+    }
+
+    @Override
+    @NotNull
+    public HandlerList getHandlers() {
+        return handlers;
+    }
+
 }