First pass on new event docs (discord-jda#636)

* Restructure GenericMessageEvent (discord-jda#637)
* Added UpdateEvent abstraction
* Added note for TextChannel.deleteMessages in Message.delete documentation
* Fixed > tag in StatsUpdateEvent docs

Author: MinnDevelopment

src/main/java/net/dv8tion/jda/core/entities/Message.java

@@ -709,6 +709,9 @@ public interface Message extends ISnowflake, Formattable
      * a {@link net.dv8tion.jda.core.entities.TextChannel TextChannel} and the current account has
      * {@link net.dv8tion.jda.core.Permission#MESSAGE_MANAGE Permission.MESSAGE_MANAGE} in the channel.
      *
+     * <p><u>To delete up 100 messages at once in a {@link net.dv8tion.jda.core.entities.TextChannel TextChannel}
+     * you should use {@link net.dv8tion.jda.core.entities.TextChannel#deleteMessages(java.util.Collection) TextChannel.deleteMessages(Collection)}</u>
+     *
      * <p>The following {@link net.dv8tion.jda.core.requests.ErrorResponse ErrorResponses} are possible:
      * <ul>
      *     <li>{@link net.dv8tion.jda.core.requests.ErrorResponse#MISSING_ACCESS MISSING_ACCESS}
@@ -738,6 +741,8 @@ public interface Message extends ISnowflake, Formattable
      *         {@link net.dv8tion.jda.core.entities.TextChannel TextChannel}.
      *
      * @return {@link net.dv8tion.jda.core.requests.restaction.AuditableRestAction AuditableRestAction}
+     *
+     * @see    net.dv8tion.jda.core.entities.TextChannel#deleteMessages(java.util.Collection) TextChannel.deleteMessages(Collection)
      */
     @CheckReturnValue
     AuditableRestAction<Void> delete();
@@ -1217,7 +1222,7 @@ protected Response openConnection() throws IOException
 
         /**
          * The size of the attachment in bytes.
-         * <br>Example: if {@link #getSize() getSize()} returns 1024, then the attachment is 1024 bytes, or 1KB, in size.
+         * <br>Example: if {@code getSize()} returns 1024, then the attachment is 1024 bytes, or 1KiB, in size.
          *
          * @return Positive int containing the size of the Attachment.
          */

src/main/java/net/dv8tion/jda/core/events/DisconnectEvent.java

@@ -26,10 +26,10 @@
  * Indicates that JDA has been disconnected from the remote server.
  * <br>When this event is fired JDA will try to reconnect if possible
  * unless {@link net.dv8tion.jda.core.JDABuilder#setAutoReconnect(boolean) JDABuilder.setAutoReconnect(Boolean)}
- * has been provided {@code false}!
+ * has been provided {@code false} or the disconnect was too fatal.
  *
  * <p>When reconnecting was successful either a {@link net.dv8tion.jda.core.events.ReconnectedEvent ReconnectEvent}
- * or a {@link net.dv8tion.jda.core.events.ResumedEvent ResumedEvent} is fired
+ * or a {@link net.dv8tion.jda.core.events.ResumedEvent ResumedEvent} is fired.
  */
 public class DisconnectEvent extends Event
 {
@@ -38,10 +38,12 @@ public class DisconnectEvent extends Event
     protected final boolean closedByServer;
     protected final OffsetDateTime disconnectTime;
 
-    public DisconnectEvent(JDA api, WebSocketFrame serverCloseFrame, WebSocketFrame clientCloseFrame, boolean closedByServer,
-                           OffsetDateTime disconnectTime)
+    public DisconnectEvent(
+        JDA api,
+        WebSocketFrame serverCloseFrame, WebSocketFrame clientCloseFrame,
+        boolean closedByServer, OffsetDateTime disconnectTime)
     {
-        super(api, -1);
+        super(api);
         this.serverCloseFrame = serverCloseFrame;
         this.clientCloseFrame = clientCloseFrame;
         this.closedByServer = closedByServer;
@@ -76,21 +78,41 @@ public List<String> getCloudflareRays()
         return api.getCloudflareRays();
     }
 
+    /**
+     * The close frame discord sent to us
+     *
+     * @return The {@link com.neovisionaries.ws.client.WebSocketFrame WebSocketFrame} discord sent as closing handshake
+     */
     public WebSocketFrame getServiceCloseFrame()
     {
         return serverCloseFrame;
     }
 
+    /**
+     * The close frame we sent to discord
+     *
+     * @return The {@link com.neovisionaries.ws.client.WebSocketFrame WebSocketFrame} we sent as closing handshake
+     */
     public WebSocketFrame getClientCloseFrame()
     {
         return clientCloseFrame;
     }
 
+    /**
+     * Whether the connection was closed by discord
+     *
+     * @return True, if discord closed our connection
+     */
     public boolean isClosedByServer()
     {
         return closedByServer;
     }
 
+    /**
+     * Time at which we noticed the disconnection
+     *
+     * @return Time of closure
+     */
     public OffsetDateTime getDisconnectTime()
     {
         return disconnectTime;

src/main/java/net/dv8tion/jda/core/events/Event.java

@@ -18,32 +18,47 @@
 import net.dv8tion.jda.core.JDA;
 
 /**
- * <b><u>Event</u></b><br>
- * Fired for every event.<br>
- * All events JDA fires are based on an instance of this class.<br>
- * <br>
- * Use: Used in {@link net.dv8tion.jda.core.hooks.EventListener EventListener} implementations to distinguish what event is being fired.<br><br>
- * Example implementation: {@link net.dv8tion.jda.core.hooks.ListenerAdapter ListenerAdapter}
+ * Top-level event type
+ * <br>All events JDA fires are derived from this class.
+ *
+ * <p>Can be used to check if an Object is a JDA event in {@link net.dv8tion.jda.core.hooks.EventListener EventListener} implementations to distinguish what event is being fired.
+ * <br>Adapter implementation: {@link net.dv8tion.jda.core.hooks.ListenerAdapter ListenerAdapter}
  */
 public abstract class Event
 {
     protected final JDA api;
     protected final long responseNumber;
 
+    /**
+     * Creates a new Event from the given JDA instance
+     *
+     * @param api
+     *        Current JDA instance
+     * @param responseNumber
+     *        The sequence number for this event
+     *
+     * @see   #Event(net.dv8tion.jda.core.JDA)
+     */
     public Event(JDA api, long responseNumber)
     {
         this.api = api;
         this.responseNumber = responseNumber;
     }
 
+    /**
+     * Creates a new Event from the given JDA instance
+     * <br>Uses the current {@link net.dv8tion.jda.core.JDA#getResponseTotal()} as sequence
+     *
+     * @param api
+     *        Current JDA instance
+     */
     public Event(JDA api)
     {
-        this.api = api;
-        this.responseNumber = api.getResponseTotal();
+        this(api, api.getResponseTotal());
     }
 
     /**
-     * Returns the JDA instance corresponding to this Event
+     * The current JDA instance corresponding to this Event
      *
      * @return The corresponding JDA instance
      */
@@ -52,6 +67,12 @@ public JDA getJDA()
         return api;
     }
 
+    /**
+     * The current sequence for this event.
+     * <br>This can be used to keep events in order when making sequencing system.
+     *
+     * @return The current sequence number for this event
+     */
     public long getResponseNumber()
     {
         return responseNumber;

src/main/java/net/dv8tion/jda/core/events/ExceptionEvent.java

@@ -19,8 +19,9 @@
 import net.dv8tion.jda.core.JDA;
 
 /**
- * Fired when JDA does not have a specific handling for a Throwable.
- * <br>This includes {@link java.lang.Error Errors} and {@link com.neovisionaries.ws.client.WebSocketException WebSocketExceptions}
+ * Indicates that JDA encountered a Throwable that could not be forwarded to another end-user frontend.
+ * <br>For instance this is fired for events in internal WebSocket handling or audio threads.
+ * This includes {@link java.lang.Error Errors} and {@link com.neovisionaries.ws.client.WebSocketException WebSocketExceptions}
  *
  * <p>It is not recommended to simply use this and print each event as some throwables where already logged
  * by JDA. See {@link #isLogged()}.
@@ -32,7 +33,7 @@ public class ExceptionEvent extends Event
 
     public ExceptionEvent(JDA api, Throwable throwable, boolean logged)
     {
-        super(api, -1);
+        super(api);
         this.throwable = throwable;
         this.logged = logged;
     }

src/main/java/net/dv8tion/jda/core/events/ReadyEvent.java

@@ -18,11 +18,11 @@
 import net.dv8tion.jda.core.JDA;
 
 /**
- * <b><u>ReadyEvent</u></b><br>
- * Fired if our connection finished loading the ready event.<br>
- * Before this event was fired all entity related functions (like JDA#getUserById(String)) were not guaranteed to work as expected.<br>
- * <br>
- * Use: JDA finished populating internal objects and is now ready to be used. When this is fired all entities are cached and accessible.
+ * Indicates that JDA finished loading all entities.
+ * <br>Before this event was fired all entity related functions were not guaranteed to work as expected.
+ *
+ * <p>Can be used to indicate when JDA finished populating internal objects and is ready to be used.
+ * When this is fired all entities are cached and accessible.
  */
 public class ReadyEvent extends Event
 {

src/main/java/net/dv8tion/jda/core/events/ReconnectedEvent.java

@@ -18,11 +18,11 @@
 import net.dv8tion.jda.core.JDA;
 
 /**
- * <b><u>ReconnectedEvent</u></b><br>
- * Fired if JDA successfully re-established it's connection to the WebSocket.<br>
- * All Objects have been replaced when this is fired and events were likely missed in the downtime.<br>
- * <br>
- * Use: This marks the continuation of event flow stopped by the {@link net.dv8tion.jda.core.events.DisconnectEvent DisconnectEvent}. User should replace any cached Objects (like User/Guild objects).
+ * Indicates if JDA successfully re-established its connection to the gateway.
+ * <br>All Objects have been replaced when this is fired and events were likely missed in the downtime.
+ *
+ * <p>Can be used to mark the continuation of event flow which was stopped by the {@link net.dv8tion.jda.core.events.DisconnectEvent DisconnectEvent}.
+ * User should replace any cached Objects (like User/Guild objects).
  */
 public class ReconnectedEvent extends Event
 {

src/main/java/net/dv8tion/jda/core/events/ResumedEvent.java

@@ -18,11 +18,10 @@
 import net.dv8tion.jda.core.JDA;
 
 /**
- * <b><u>ResumedEvent</u></b><br>
- * Fired if JDA successfully re-established it's connection to the WebSocket.<br>
- * All Objects are still in place and events are replayed.<br>
- * <br>
- * Use: This marks the continuation of event flow stopped by the {@link net.dv8tion.jda.core.events.DisconnectEvent DisconnectEvent}.
+ * Indicates that JDA successfully resumed its connection to the gateway.
+ * <br>All Objects are still in place and events are replayed.
+ *
+ * <p>Can be used to marks the continuation of event flow stopped by the {@link net.dv8tion.jda.core.events.DisconnectEvent DisconnectEvent}.
  */
 public class ResumedEvent extends Event
 {

src/main/java/net/dv8tion/jda/core/events/ShutdownEvent.java

@@ -21,8 +21,7 @@
 import java.time.OffsetDateTime;
 
 /**
- * Indicates that JDA has fully disconnected from Discord
- * and will not attempt to reconnect again.
+ * Indicates that JDA has fully disconnected from Discord and will not attempt to reconnect again.
  * <br>At this stage all internal cache is invalid!
  */
 public class ShutdownEvent extends Event
@@ -32,7 +31,7 @@ public class ShutdownEvent extends Event
 
     public ShutdownEvent(JDA api, OffsetDateTime shutdownTime, int code)
     {
-        super(api, -1);
+        super(api);
         this.shutdownTime = shutdownTime;
         this.code = code;
     }

src/main/java/net/dv8tion/jda/core/events/StatusChangeEvent.java

@@ -18,30 +18,87 @@
 import net.dv8tion.jda.core.JDA;
 
 /**
- * <b><u>StatusChangedEvent</u></b><br>
- * Fired if our {@link net.dv8tion.jda.core.JDA.Status Status} changed. (Example: SHUTTING_DOWN -&gt; SHUTDOWN)<br>
- * <br>
- * Use: Detect internal status changes. Possibly to log or forward on user's end.
+ * Indicates that our {@link net.dv8tion.jda.core.JDA.Status Status} changed. (Example: SHUTTING_DOWN {@literal ->} SHUTDOWN)
+ *
+ * <br>Can be used to detect internal status changes. Possibly to log or forward on user's end.
+ *
+ * <p>Identifier: {@code status}
  */
-public class StatusChangeEvent extends Event
+public class StatusChangeEvent extends Event implements UpdateEvent<JDA, JDA.Status>
 {
+    public static final String IDENTIFIER = "status";
+
     protected final JDA.Status newStatus;
     protected final JDA.Status oldStatus;
 
     public StatusChangeEvent(JDA api, JDA.Status newStatus, JDA.Status oldStatus)
     {
-        super(api, -1);
+        super(api);
         this.newStatus = newStatus;
         this.oldStatus = oldStatus;
     }
 
+    /**
+     * The status that we changed to
+     *
+     * @return The new status
+     *
+     * @deprecated
+     *         Use {@link #getNewStatus()} instead
+     */
+    @Deprecated
     public JDA.Status getStatus()
     {
         return newStatus;
     }
 
+    /**
+     * The status that we changed to
+     *
+     * @return The new status
+     */
+    public JDA.Status getNewStatus()
+    {
+        return newStatus;
+    }
+
+    /**
+     * The previous status
+     *
+     * @return The previous status
+     */
     public JDA.Status getOldStatus()
     {
         return oldStatus;
     }
+
+    @Override
+    public String getPropertyIdentifier()
+    {
+        return IDENTIFIER;
+    }
+
+    @Override
+    public JDA getEntity()
+    {
+        return getJDA();
+    }
+
+    @Override
+    public JDA.Status getOldValue()
+    {
+        return oldStatus;
+    }
+
+    @Override
+    public JDA.Status getNewValue()
+    {
+        return newStatus;
+    }
+
+    @Override
+    public String toString()
+    {
+        return "StatusUpdate(" + getOldStatus() + "->" + getNewStatus() + ')';
+    }
 }