Upstream/Ascension
1
0
Fork 0
mirror of https://github.com/DiscordSRV/Ascension.git synced 2024-11-22 11:55:54 +01:00
Code Issues Packages Projects Releases Wiki Activity

Improve api module documentation

Browse Source
This commit is contained in:
Vankka 2023-07-18 23:50:48 +03:00
parent 5d87915eaa
commit 3c71ade347
No known key found for this signature in database
GPG Key ID: 6E50CB7A29B96AD0
21 changed files with 88 additions and 4 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

2
api/src/main/java/com/discordsrv/api/channel/GameChannel.java
View File

@ -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 {

5
api/src/main/java/com/discordsrv/api/event/events/channel/GameChannelLookupEvent.java
View File

@ -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) {

4
api/src/main/java/com/discordsrv/api/event/events/lifecycle/DiscordSRVShuttingDownEvent.java
View File

@ -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/>
*

3
api/src/main/java/com/discordsrv/api/event/events/message/forward/discord/DiscordChatMessageForwardedEvent.java
View File

@ -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;

3
api/src/main/java/com/discordsrv/api/event/events/message/forward/game/AwardMessageForwardedEvent.java
View File

@ -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) {

3
api/src/main/java/com/discordsrv/api/event/events/message/forward/game/DeathMessageForwardedEvent.java
View File

@ -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) {

3
api/src/main/java/com/discordsrv/api/event/events/message/forward/game/GameChatMessageForwardedEvent.java
View File

@ -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) {

3
api/src/main/java/com/discordsrv/api/event/events/message/forward/game/JoinMessageForwardedEvent.java
View File

@ -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) {

3
api/src/main/java/com/discordsrv/api/event/events/message/forward/game/LeaveMessageForwardedEvent.java
View File

@ -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) {

3
api/src/main/java/com/discordsrv/api/event/events/message/forward/game/ServerSwitchMessageForwardedEvent.java
View File

@ -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) {

4
api/src/main/java/com/discordsrv/api/event/events/message/receive/discord/DiscordChatMessageProcessEvent.java
View File

@ -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;

4
api/src/main/java/com/discordsrv/api/event/events/message/receive/discord/DiscordChatMessageReceiveEvent.java
View File

@ -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;

4
api/src/main/java/com/discordsrv/api/event/events/message/receive/game/AbstractGameMessageReceiveEvent.java
View File

@ -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;

4
api/src/main/java/com/discordsrv/api/event/events/message/receive/game/AwardMessageReceiveEvent.java
View File

@ -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;

4
api/src/main/java/com/discordsrv/api/event/events/message/receive/game/DeathMessageReceiveEvent.java
View File

@ -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;

4
api/src/main/java/com/discordsrv/api/event/events/message/receive/game/GameChatMessageReceiveEvent.java
View File

@ -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;

4
api/src/main/java/com/discordsrv/api/event/events/message/receive/game/JoinMessageReceiveEvent.java
View File

@ -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;

4
api/src/main/java/com/discordsrv/api/event/events/message/receive/game/LeaveMessageReceiveEvent.java
View File

@ -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;

4
api/src/main/java/com/discordsrv/api/event/events/message/receive/game/ServerSwitchMessageReceiveEvent.java
View File

@ -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;

17
api/src/main/java/com/discordsrv/api/event/events/placeholder/PlaceholderLookupEvent.java
View File

@ -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) {

7
api/src/main/java/com/discordsrv/api/profile/IProfile.java
View File

@ -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;
}