Document and clean up API events

Essentials/src/net/ess3/api/events/GodStatusChangeEvent.java

@@ -3,6 +3,12 @@ package net.ess3.api.events;
 import net.ess3.api.IUser;
 
 
+/**
+ * Fired when a user's god status is toggled.
+ *
+ * Note that in older versions (original Essentials and early EssentialsX), the #getAffected
+ * and #getController methods are inverted.
+ */
 public class GodStatusChangeEvent extends StatusChangeEvent {
     public GodStatusChangeEvent(IUser affected, IUser controller, boolean value) {
         super(affected, controller, value);

Essentials/src/net/ess3/api/events/IgnoreStatusChangeEvent.java

@@ -2,7 +2,9 @@ package net.ess3.api.events;
 
 import net.ess3.api.IUser;
 
-
+/**
+ * This event is currently unused, and is retained for ABI compatibility and potential future implementation.
+ */
 public class IgnoreStatusChangeEvent extends StatusChangeEvent {
     public IgnoreStatusChangeEvent(IUser affected, IUser controller, boolean value) {
         super(affected, controller, value);

Essentials/src/net/ess3/api/events/NickChangeEvent.java

@@ -15,4 +15,26 @@ public class NickChangeEvent extends StateChangeEvent implements Cancellable {
     public String getValue() {
         return newValue;
     }
+
+    /**
+     * Get the user who CAUSED the state change.
+     * (This method is implemented incorrectly.)
+     *
+     * @return The user who <b>caused the state change</b>.
+     */
+    @Override
+    public IUser getAffected() {
+        return super.getAffected();
+    }
+
+    /**
+     * Get the user who is AFFECTED by the state change.
+     * (This method is implemented incorrectly.)
+     *
+     * @return The user who <b>is affected by the state change</b>.
+     */
+    @Override
+    public IUser getController() {
+        return super.getController();
+    }
 }

Essentials/src/net/ess3/api/events/StateChangeEvent.java

@@ -7,9 +7,10 @@ import org.bukkit.event.HandlerList;
 
 
 /**
- * This handles common boilerplate for other StateChangeEvents
+ * This handles common boilerplate for events for changes in state.
+ * For boolean state, events should extend StatusChangeEvent instead.
  */
-public class StateChangeEvent extends Event implements Cancellable {
+public abstract class StateChangeEvent extends Event implements Cancellable {
     private static final HandlerList handlers = new HandlerList();
     private boolean cancelled = false;
     IUser affected;
@@ -27,10 +28,20 @@ public class StateChangeEvent extends Event implements Cancellable {
         this.controller = controller;
     }
 
+    /**
+     * Get the user who is affected by the state change.
+     *
+     * @return The user who is affected by the state change.
+     */
     public IUser getAffected() {
         return this.affected;
     }
 
+    /**
+     * Get the user who caused the state change.
+     *
+     * @return The user who caused the state change.
+     */
     public IUser getController() {
         return controller;
     }

Essentials/src/net/ess3/api/events/StatusChangeEvent.java

@@ -6,9 +6,9 @@ import org.bukkit.event.Cancellable;
 
 
 /**
- * This handles common boilerplate for other StatusChangeEvents
+ * This handles common boilerplate for events for changes in state that are boolean (true/false).
  */
-public class StatusChangeEvent extends StateChangeEvent implements Cancellable {
+public abstract class StatusChangeEvent extends StateChangeEvent implements Cancellable {
     private boolean newValue;
 
     public StatusChangeEvent(IUser affected, IUser controller, boolean value) {

Essentials/src/net/ess3/api/events/VanishStatusChangeEvent.java

@@ -3,7 +3,10 @@ package net.ess3.api.events;
 import net.ess3.api.IUser;
 
 /**
- * Called only in Commandvanish. For other events please use classes such as PlayerJoinEvent and eventually {@link IUser#isVanished()}.
+ * Fired when a player's vanish status changes due to the /vanish command.
+ *
+ * For other cases where the player's vanish status changes, you should listen on PlayerJoinEvent and
+ * check with {@link IUser#isVanished()}.
  */
 public class VanishStatusChangeEvent extends StatusChangeEvent {
     public VanishStatusChangeEvent(IUser affected, IUser controller, boolean value) {