From 3c71ade347101f4c49d3cb9f07c1a73c9494fded Mon Sep 17 00:00:00 2001
From: Vankka <vankka.main@gmail.com>
Date: Tue, 18 Jul 2023 23:50:48 +0300
Subject: [PATCH] Improve api module documentation

---
 .../com/discordsrv/api/channel/GameChannel.java |  2 +-
 .../events/channel/GameChannelLookupEvent.java  |  5 ++++-
 .../lifecycle/DiscordSRVShuttingDownEvent.java  |  4 ++--
 .../DiscordChatMessageForwardedEvent.java       |  3 +++
 .../game/AwardMessageForwardedEvent.java        |  3 +++
 .../game/DeathMessageForwardedEvent.java        |  3 +++
 .../game/GameChatMessageForwardedEvent.java     |  3 +++
 .../forward/game/JoinMessageForwardedEvent.java |  3 +++
 .../game/LeaveMessageForwardedEvent.java        |  3 +++
 .../game/ServerSwitchMessageForwardedEvent.java |  3 +++
 .../discord/DiscordChatMessageProcessEvent.java |  4 ++++
 .../discord/DiscordChatMessageReceiveEvent.java |  4 ++++
 .../game/AbstractGameMessageReceiveEvent.java   |  4 ++++
 .../receive/game/AwardMessageReceiveEvent.java  |  4 ++++
 .../receive/game/DeathMessageReceiveEvent.java  |  4 ++++
 .../game/GameChatMessageReceiveEvent.java       |  4 ++++
 .../receive/game/JoinMessageReceiveEvent.java   |  4 ++++
 .../receive/game/LeaveMessageReceiveEvent.java  |  4 ++++
 .../game/ServerSwitchMessageReceiveEvent.java   |  4 ++++
 .../placeholder/PlaceholderLookupEvent.java     | 17 +++++++++++++++++
 .../com/discordsrv/api/profile/IProfile.java    |  7 +++++++
 21 files changed, 88 insertions(+), 4 deletions(-)

diff --git a/api/src/main/java/com/discordsrv/api/channel/GameChannel.java b/api/src/main/java/com/discordsrv/api/channel/GameChannel.java
index 18030baf..4d72fb87 100644
--- a/api/src/main/java/com/discordsrv/api/channel/GameChannel.java
+++ b/api/src/main/java/com/discordsrv/api/channel/GameChannel.java
@@ -27,7 +27,7 @@ import com.discordsrv.api.component.MinecraftComponent;
 import org.jetbrains.annotations.NotNull;
 
 /**
- * An in-game channel for sending Minecraft messages.
+ * An in-game channel for sending Minecraft messages to.
  */
 public interface GameChannel {
 
diff --git a/api/src/main/java/com/discordsrv/api/event/events/channel/GameChannelLookupEvent.java b/api/src/main/java/com/discordsrv/api/event/events/channel/GameChannelLookupEvent.java
index ecb7d222..9110458b 100644
--- a/api/src/main/java/com/discordsrv/api/event/events/channel/GameChannelLookupEvent.java
+++ b/api/src/main/java/com/discordsrv/api/event/events/channel/GameChannelLookupEvent.java
@@ -32,6 +32,8 @@ import org.jetbrains.annotations.Nullable;
  * This event is used to lookup {@link GameChannel}s by their name (and optionally plugin name).
  * This is also used to determine which plugin's channel should take priority when multiple plugins
  * define channels with the same name ({@link com.discordsrv.api.event.bus.EventPriority}).
+ *
+ * @see #isDefault()
  */
 public class GameChannelLookupEvent implements Processable {
 
@@ -47,7 +49,7 @@ public class GameChannelLookupEvent implements Processable {
     }
 
     /**
-     * If this is for the "default" channel.
+     * If this is {@code true} the default channel should be returned, if it exists.
      * @return if this lookup is for the default channel
      */
     public boolean isDefault() {
@@ -86,6 +88,7 @@ public class GameChannelLookupEvent implements Processable {
      * If this is the {@link #isDefault()} channel, any channel name is accepted.
      * @param channel the channel
      * @throws IllegalStateException if the event is already processed
+     * @throws IllegalArgumentException if the provided channel doesn't match {@link #getChannelName()} and {@link #isDefault()} is {@code false}
      */
     public void process(@NotNull GameChannel channel) {
         if (processed) {
diff --git a/api/src/main/java/com/discordsrv/api/event/events/lifecycle/DiscordSRVShuttingDownEvent.java b/api/src/main/java/com/discordsrv/api/event/events/lifecycle/DiscordSRVShuttingDownEvent.java
index 91849d92..d0aa86f2 100644
--- a/api/src/main/java/com/discordsrv/api/event/events/lifecycle/DiscordSRVShuttingDownEvent.java
+++ b/api/src/main/java/com/discordsrv/api/event/events/lifecycle/DiscordSRVShuttingDownEvent.java
@@ -28,8 +28,8 @@ import com.discordsrv.api.event.events.Event;
 
 /**
  * Indicates that DiscordSRV is shutting down.
- *
- * DiscordSRV's own systems will shutdown at the following times:
+ * <p>
+ * DiscordSRV's own systems will shut down at the following times:
  * {@link EventPriority#EARLY}<br/>
  *  - DiscordSRV's own modules shutdown<br/>
  *
diff --git a/api/src/main/java/com/discordsrv/api/event/events/message/forward/discord/DiscordChatMessageForwardedEvent.java b/api/src/main/java/com/discordsrv/api/event/events/message/forward/discord/DiscordChatMessageForwardedEvent.java
index 6a5c57e1..fae1c8ad 100644
--- a/api/src/main/java/com/discordsrv/api/event/events/message/forward/discord/DiscordChatMessageForwardedEvent.java
+++ b/api/src/main/java/com/discordsrv/api/event/events/message/forward/discord/DiscordChatMessageForwardedEvent.java
@@ -28,6 +28,9 @@ import com.discordsrv.api.component.MinecraftComponent;
 import com.discordsrv.api.event.events.Event;
 import org.jetbrains.annotations.NotNull;
 
+/**
+ * Indicates that a message from Discord was forwarded to the provided {@link GameChannel}.
+ */
 public class DiscordChatMessageForwardedEvent implements Event {
 
     private final MinecraftComponent message;
diff --git a/api/src/main/java/com/discordsrv/api/event/events/message/forward/game/AwardMessageForwardedEvent.java b/api/src/main/java/com/discordsrv/api/event/events/message/forward/game/AwardMessageForwardedEvent.java
index c71db081..509248f3 100644
--- a/api/src/main/java/com/discordsrv/api/event/events/message/forward/game/AwardMessageForwardedEvent.java
+++ b/api/src/main/java/com/discordsrv/api/event/events/message/forward/game/AwardMessageForwardedEvent.java
@@ -26,6 +26,9 @@ package com.discordsrv.api.event.events.message.forward.game;
 import com.discordsrv.api.discord.entity.message.ReceivedDiscordMessageCluster;
 import org.jetbrains.annotations.NotNull;
 
+/**
+ * Indicates that an advancement or achievement message was forwarded to Discord.
+ */
 public class AwardMessageForwardedEvent extends AbstractGameMessageForwardedEvent {
 
     public AwardMessageForwardedEvent(@NotNull ReceivedDiscordMessageCluster discordMessage) {
diff --git a/api/src/main/java/com/discordsrv/api/event/events/message/forward/game/DeathMessageForwardedEvent.java b/api/src/main/java/com/discordsrv/api/event/events/message/forward/game/DeathMessageForwardedEvent.java
index 10690f9e..a6e892f6 100644
--- a/api/src/main/java/com/discordsrv/api/event/events/message/forward/game/DeathMessageForwardedEvent.java
+++ b/api/src/main/java/com/discordsrv/api/event/events/message/forward/game/DeathMessageForwardedEvent.java
@@ -26,6 +26,9 @@ package com.discordsrv.api.event.events.message.forward.game;
 import com.discordsrv.api.discord.entity.message.ReceivedDiscordMessageCluster;
 import org.jetbrains.annotations.NotNull;
 
+/**
+ * Indicates that a death message was forwarded to Discord.
+ */
 public class DeathMessageForwardedEvent extends AbstractGameMessageForwardedEvent {
 
     public DeathMessageForwardedEvent(@NotNull ReceivedDiscordMessageCluster discordMessage) {
diff --git a/api/src/main/java/com/discordsrv/api/event/events/message/forward/game/GameChatMessageForwardedEvent.java b/api/src/main/java/com/discordsrv/api/event/events/message/forward/game/GameChatMessageForwardedEvent.java
index 53193c3c..1d012aee 100644
--- a/api/src/main/java/com/discordsrv/api/event/events/message/forward/game/GameChatMessageForwardedEvent.java
+++ b/api/src/main/java/com/discordsrv/api/event/events/message/forward/game/GameChatMessageForwardedEvent.java
@@ -26,6 +26,9 @@ package com.discordsrv.api.event.events.message.forward.game;
 import com.discordsrv.api.discord.entity.message.ReceivedDiscordMessageCluster;
 import org.jetbrains.annotations.NotNull;
 
+/**
+ * Indicates that a chat message was forwarded to Discord.
+ */
 public class GameChatMessageForwardedEvent extends AbstractGameMessageForwardedEvent {
 
     public GameChatMessageForwardedEvent(@NotNull ReceivedDiscordMessageCluster discordMessage) {
diff --git a/api/src/main/java/com/discordsrv/api/event/events/message/forward/game/JoinMessageForwardedEvent.java b/api/src/main/java/com/discordsrv/api/event/events/message/forward/game/JoinMessageForwardedEvent.java
index ef657603..07ff6d1a 100644
--- a/api/src/main/java/com/discordsrv/api/event/events/message/forward/game/JoinMessageForwardedEvent.java
+++ b/api/src/main/java/com/discordsrv/api/event/events/message/forward/game/JoinMessageForwardedEvent.java
@@ -26,6 +26,9 @@ package com.discordsrv.api.event.events.message.forward.game;
 import com.discordsrv.api.discord.entity.message.ReceivedDiscordMessageCluster;
 import org.jetbrains.annotations.NotNull;
 
+/**
+ * Indicates that a join message was forwarded to Discord.
+ */
 public class JoinMessageForwardedEvent extends AbstractGameMessageForwardedEvent {
 
     public JoinMessageForwardedEvent(@NotNull ReceivedDiscordMessageCluster discordMessage) {
diff --git a/api/src/main/java/com/discordsrv/api/event/events/message/forward/game/LeaveMessageForwardedEvent.java b/api/src/main/java/com/discordsrv/api/event/events/message/forward/game/LeaveMessageForwardedEvent.java
index 8598851f..ed4e9056 100644
--- a/api/src/main/java/com/discordsrv/api/event/events/message/forward/game/LeaveMessageForwardedEvent.java
+++ b/api/src/main/java/com/discordsrv/api/event/events/message/forward/game/LeaveMessageForwardedEvent.java
@@ -26,6 +26,9 @@ package com.discordsrv.api.event.events.message.forward.game;
 import com.discordsrv.api.discord.entity.message.ReceivedDiscordMessageCluster;
 import org.jetbrains.annotations.NotNull;
 
+/**
+ * Indicates that a leave message was forwarded to Discord.
+ */
 public class LeaveMessageForwardedEvent extends AbstractGameMessageForwardedEvent {
 
     public LeaveMessageForwardedEvent(@NotNull ReceivedDiscordMessageCluster discordMessage) {
diff --git a/api/src/main/java/com/discordsrv/api/event/events/message/forward/game/ServerSwitchMessageForwardedEvent.java b/api/src/main/java/com/discordsrv/api/event/events/message/forward/game/ServerSwitchMessageForwardedEvent.java
index cf584058..960b8bee 100644
--- a/api/src/main/java/com/discordsrv/api/event/events/message/forward/game/ServerSwitchMessageForwardedEvent.java
+++ b/api/src/main/java/com/discordsrv/api/event/events/message/forward/game/ServerSwitchMessageForwardedEvent.java
@@ -26,6 +26,9 @@ package com.discordsrv.api.event.events.message.forward.game;
 import com.discordsrv.api.discord.entity.message.ReceivedDiscordMessageCluster;
 import org.jetbrains.annotations.NotNull;
 
+/**
+ * Indicates that a server switch message was forwarded to Discord.
+ */
 public class ServerSwitchMessageForwardedEvent extends AbstractGameMessageForwardedEvent {
 
     public ServerSwitchMessageForwardedEvent(@NotNull ReceivedDiscordMessageCluster discordMessage) {
diff --git a/api/src/main/java/com/discordsrv/api/event/events/message/receive/discord/DiscordChatMessageProcessEvent.java b/api/src/main/java/com/discordsrv/api/event/events/message/receive/discord/DiscordChatMessageProcessEvent.java
index c0396e5f..2519af1b 100644
--- a/api/src/main/java/com/discordsrv/api/event/events/message/receive/discord/DiscordChatMessageProcessEvent.java
+++ b/api/src/main/java/com/discordsrv/api/event/events/message/receive/discord/DiscordChatMessageProcessEvent.java
@@ -6,6 +6,10 @@ import com.discordsrv.api.discord.entity.message.ReceivedDiscordMessage;
 import com.discordsrv.api.event.events.Cancellable;
 import com.discordsrv.api.event.events.Processable;
 
+/**
+ * Indicates that a Discord message is about to be processed, this will run once per {@link GameChannel} destination,
+ * meaning it could run multiple times for a single Discord message. This runs after {@link DiscordChatMessageReceiveEvent}.
+ */
 public class DiscordChatMessageProcessEvent implements Cancellable, Processable {
 
     private final DiscordMessageChannel discordChannel;
diff --git a/api/src/main/java/com/discordsrv/api/event/events/message/receive/discord/DiscordChatMessageReceiveEvent.java b/api/src/main/java/com/discordsrv/api/event/events/message/receive/discord/DiscordChatMessageReceiveEvent.java
index 432b5f7a..042176d1 100644
--- a/api/src/main/java/com/discordsrv/api/event/events/message/receive/discord/DiscordChatMessageReceiveEvent.java
+++ b/api/src/main/java/com/discordsrv/api/event/events/message/receive/discord/DiscordChatMessageReceiveEvent.java
@@ -31,6 +31,10 @@ import com.discordsrv.api.discord.entity.message.ReceivedDiscordMessage;
 import com.discordsrv.api.event.events.Cancellable;
 import org.jetbrains.annotations.NotNull;
 
+/**
+ * Indicates that a Discord message has been received and will be processed unless cancelled.
+ * This runs once per Discord message, before {@link DiscordChatMessageProcessEvent}.
+ */
 public class DiscordChatMessageReceiveEvent implements Cancellable {
 
     private final ReceivedDiscordMessage message;
diff --git a/api/src/main/java/com/discordsrv/api/event/events/message/receive/game/AbstractGameMessageReceiveEvent.java b/api/src/main/java/com/discordsrv/api/event/events/message/receive/game/AbstractGameMessageReceiveEvent.java
index 975da6a1..7d3e45f5 100644
--- a/api/src/main/java/com/discordsrv/api/event/events/message/receive/game/AbstractGameMessageReceiveEvent.java
+++ b/api/src/main/java/com/discordsrv/api/event/events/message/receive/game/AbstractGameMessageReceiveEvent.java
@@ -38,6 +38,10 @@ public abstract class AbstractGameMessageReceiveEvent implements Processable, Ca
         this.cancelled = cancelled;
     }
 
+    /**
+     * Gets the event that triggered this event to occur. This varies depending on platform and different plugin integrations.
+     * @return an event object, that isn't guaranteed to be of the same type every time or {@code null}
+     */
     @Nullable
     public Object getTriggeringEvent() {
         return triggeringEvent;
diff --git a/api/src/main/java/com/discordsrv/api/event/events/message/receive/game/AwardMessageReceiveEvent.java b/api/src/main/java/com/discordsrv/api/event/events/message/receive/game/AwardMessageReceiveEvent.java
index ba0138c0..f3a32d14 100644
--- a/api/src/main/java/com/discordsrv/api/event/events/message/receive/game/AwardMessageReceiveEvent.java
+++ b/api/src/main/java/com/discordsrv/api/event/events/message/receive/game/AwardMessageReceiveEvent.java
@@ -29,6 +29,10 @@ import com.discordsrv.api.player.DiscordSRVPlayer;
 import org.jetbrains.annotations.NotNull;
 import org.jetbrains.annotations.Nullable;
 
+/**
+ * Indicates that an advancement or achievement message was received will be processed
+ * at {@link com.discordsrv.api.event.bus.EventPriority#DEFAULT} unless cancelled or processed by a 3rd party.
+ */
 public class AwardMessageReceiveEvent extends AbstractGameMessageReceiveEvent {
 
     private final DiscordSRVPlayer player;
diff --git a/api/src/main/java/com/discordsrv/api/event/events/message/receive/game/DeathMessageReceiveEvent.java b/api/src/main/java/com/discordsrv/api/event/events/message/receive/game/DeathMessageReceiveEvent.java
index bedb432a..043d8d77 100644
--- a/api/src/main/java/com/discordsrv/api/event/events/message/receive/game/DeathMessageReceiveEvent.java
+++ b/api/src/main/java/com/discordsrv/api/event/events/message/receive/game/DeathMessageReceiveEvent.java
@@ -29,6 +29,10 @@ import com.discordsrv.api.player.DiscordSRVPlayer;
 import org.jetbrains.annotations.NotNull;
 import org.jetbrains.annotations.Nullable;
 
+/**
+ * Indicates that a death message was received and will be processed
+ * at {@link com.discordsrv.api.event.bus.EventPriority#DEFAULT} unless cancelled or processed by a 3rd party.
+ */
 public class DeathMessageReceiveEvent extends AbstractGameMessageReceiveEvent {
 
     private final DiscordSRVPlayer player;
diff --git a/api/src/main/java/com/discordsrv/api/event/events/message/receive/game/GameChatMessageReceiveEvent.java b/api/src/main/java/com/discordsrv/api/event/events/message/receive/game/GameChatMessageReceiveEvent.java
index 259282c9..e4acfb19 100644
--- a/api/src/main/java/com/discordsrv/api/event/events/message/receive/game/GameChatMessageReceiveEvent.java
+++ b/api/src/main/java/com/discordsrv/api/event/events/message/receive/game/GameChatMessageReceiveEvent.java
@@ -30,6 +30,10 @@ import com.discordsrv.api.player.DiscordSRVPlayer;
 import org.jetbrains.annotations.NotNull;
 import org.jetbrains.annotations.Nullable;
 
+/**
+ * Indicates that a chat message was received and will be processed
+ * at {@link com.discordsrv.api.event.bus.EventPriority#DEFAULT} unless cancelled or processed by a 3rd party.
+ */
 public class GameChatMessageReceiveEvent extends AbstractGameMessageReceiveEvent implements PlayerEvent {
 
     private final DiscordSRVPlayer player;
diff --git a/api/src/main/java/com/discordsrv/api/event/events/message/receive/game/JoinMessageReceiveEvent.java b/api/src/main/java/com/discordsrv/api/event/events/message/receive/game/JoinMessageReceiveEvent.java
index c8f09ce6..99cc73c8 100644
--- a/api/src/main/java/com/discordsrv/api/event/events/message/receive/game/JoinMessageReceiveEvent.java
+++ b/api/src/main/java/com/discordsrv/api/event/events/message/receive/game/JoinMessageReceiveEvent.java
@@ -29,6 +29,10 @@ import com.discordsrv.api.player.DiscordSRVPlayer;
 import org.jetbrains.annotations.NotNull;
 import org.jetbrains.annotations.Nullable;
 
+/**
+ * Indicates that a join message was received and will be processed
+ * at {@link com.discordsrv.api.event.bus.EventPriority#DEFAULT} unless cancelled or processed by a 3rd party.
+ */
 public class JoinMessageReceiveEvent extends AbstractGameMessageReceiveEvent {
 
     private final DiscordSRVPlayer player;
diff --git a/api/src/main/java/com/discordsrv/api/event/events/message/receive/game/LeaveMessageReceiveEvent.java b/api/src/main/java/com/discordsrv/api/event/events/message/receive/game/LeaveMessageReceiveEvent.java
index d14522e4..ca5541b0 100644
--- a/api/src/main/java/com/discordsrv/api/event/events/message/receive/game/LeaveMessageReceiveEvent.java
+++ b/api/src/main/java/com/discordsrv/api/event/events/message/receive/game/LeaveMessageReceiveEvent.java
@@ -29,6 +29,10 @@ import com.discordsrv.api.player.DiscordSRVPlayer;
 import org.jetbrains.annotations.NotNull;
 import org.jetbrains.annotations.Nullable;
 
+/**
+ * Indicates that a leave message was received and will be processed
+ * at {@link com.discordsrv.api.event.bus.EventPriority#DEFAULT} unless cancelled or processed by a 3rd party.
+ */
 public class LeaveMessageReceiveEvent extends AbstractGameMessageReceiveEvent {
 
     private final DiscordSRVPlayer player;
diff --git a/api/src/main/java/com/discordsrv/api/event/events/message/receive/game/ServerSwitchMessageReceiveEvent.java b/api/src/main/java/com/discordsrv/api/event/events/message/receive/game/ServerSwitchMessageReceiveEvent.java
index 3dd02de9..47fcac64 100644
--- a/api/src/main/java/com/discordsrv/api/event/events/message/receive/game/ServerSwitchMessageReceiveEvent.java
+++ b/api/src/main/java/com/discordsrv/api/event/events/message/receive/game/ServerSwitchMessageReceiveEvent.java
@@ -28,6 +28,10 @@ import com.discordsrv.api.player.DiscordSRVPlayer;
 import org.jetbrains.annotations.NotNull;
 import org.jetbrains.annotations.Nullable;
 
+/**
+ * Indicates that a server switch message was received and will be processed
+ * at {@link com.discordsrv.api.event.bus.EventPriority#DEFAULT} unless cancelled or processed by a 3rd party.
+ */
 public class ServerSwitchMessageReceiveEvent extends AbstractGameMessageReceiveEvent {
 
     private final DiscordSRVPlayer player;
diff --git a/api/src/main/java/com/discordsrv/api/event/events/placeholder/PlaceholderLookupEvent.java b/api/src/main/java/com/discordsrv/api/event/events/placeholder/PlaceholderLookupEvent.java
index 161e7371..a6e28168 100644
--- a/api/src/main/java/com/discordsrv/api/event/events/placeholder/PlaceholderLookupEvent.java
+++ b/api/src/main/java/com/discordsrv/api/event/events/placeholder/PlaceholderLookupEvent.java
@@ -31,6 +31,9 @@ import org.jetbrains.annotations.Nullable;
 
 import java.util.Set;
 
+/**
+ * An event for converting a placeholder's name and context into a {@link PlaceholderLookupResult}.
+ */
 public class PlaceholderLookupEvent implements Event, Processable {
 
     private final String placeholder;
@@ -44,14 +47,28 @@ public class PlaceholderLookupEvent implements Event, Processable {
         this.contexts = contexts;
     }
 
+    /**
+     * The placeholders that was requested.
+     * @return the placeholder
+     */
     public String getPlaceholder() {
         return placeholder;
     }
 
+    /**
+     * Gets all contexts provided for this lookup, this may be things like {@link com.discordsrv.api.player.DiscordSRVPlayer} or {@link com.discordsrv.api.discord.entity.DiscordUser}.
+     * @return all contexts for this request
+     */
     public Set<Object> getContexts() {
         return contexts;
     }
 
+    /**
+     * Returns the context of the given type if provided.
+     * @param type the type of context to look for
+     * @return the given context if provided, otherwise {@code null}
+     * @param <T> the type of the context to lookup
+     */
     @SuppressWarnings("unchecked")
     public <T> @Nullable T getContext(Class<T> type) {
         for (Object o : contexts) {
diff --git a/api/src/main/java/com/discordsrv/api/profile/IProfile.java b/api/src/main/java/com/discordsrv/api/profile/IProfile.java
index c33d02b1..05cfce6e 100644
--- a/api/src/main/java/com/discordsrv/api/profile/IProfile.java
+++ b/api/src/main/java/com/discordsrv/api/profile/IProfile.java
@@ -27,6 +27,9 @@ import org.jetbrains.annotations.Nullable;
 
 import java.util.UUID;
 
+/**
+ * A profile for a Minecraft player, Discord user or linked pair.
+ */
 public interface IProfile {
 
     @Nullable
@@ -35,6 +38,10 @@ public interface IProfile {
     @Nullable
     Long userId();
 
+    /**
+     * If this profile belongs to a linked Player and User pair.
+     * @return {@code true} if this profile is for a linked player/user
+     */
     default boolean isLinked() {
         return playerUUID() != null && userId() != null;
     }