From 0118c0bd79d81b972a3399a694f44097e42ea3f6 Mon Sep 17 00:00:00 2001
From: Jason <11360596+jpenilla@users.noreply.github.com>
Date: Sun, 7 Aug 2022 13:47:43 -0700
Subject: [PATCH] Improve MojangAPI docs and replace @Deprecated with
@ApiStatus.Experimental on draft APIs (#8261)
---
.../AsyncPlayerSendCommandsEvent.java | 32 +++++++++++--------
.../AsyncPlayerSendSuggestionsEvent.java | 19 +++++++----
.../brigadier/CommandRegisteredEvent.java | 11 +++----
3 files changed, 36 insertions(+), 26 deletions(-)
diff --git a/Paper-MojangAPI/src/main/java/com/destroystokyo/paper/event/brigadier/AsyncPlayerSendCommandsEvent.java b/Paper-MojangAPI/src/main/java/com/destroystokyo/paper/event/brigadier/AsyncPlayerSendCommandsEvent.java
index d767aa23fe..495b0f0d2f 100644
--- a/Paper-MojangAPI/src/main/java/com/destroystokyo/paper/event/brigadier/AsyncPlayerSendCommandsEvent.java
+++ b/Paper-MojangAPI/src/main/java/com/destroystokyo/paper/event/brigadier/AsyncPlayerSendCommandsEvent.java
@@ -3,33 +3,33 @@ package com.destroystokyo.paper.event.brigadier;
import com.destroystokyo.paper.brigadier.BukkitBrigadierCommandSource;
import com.mojang.brigadier.tree.RootCommandNode;
import org.bukkit.Bukkit;
-import org.bukkit.Warning;
import org.bukkit.entity.Player;
import org.bukkit.event.HandlerList;
import org.bukkit.event.player.PlayerEvent;
+import org.jetbrains.annotations.ApiStatus;
import org.jetbrains.annotations.NotNull;
/**
* Fired any time a Brigadier RootCommandNode is generated for a player to inform the client of commands.
* You may manipulate this CommandNode to change what the client sees.
*
- * This event may fire on login, world change, and permission rebuilds, by plugin request, and potentially future means.
+ * This event may fire on login, world change, and permission rebuilds, by plugin request, and potentially future means.
*
- * This event will fire before {@link org.bukkit.event.player.PlayerCommandSendEvent}, so no filtering has been done by
- * other plugins yet.
+ * This event will fire before {@link org.bukkit.event.player.PlayerCommandSendEvent}, so no filtering has been done by
+ * other plugins yet.
*
- * WARNING: This event will potentially (and most likely) fire twice! Once for Async, and once again for Sync.
+ * WARNING: This event will potentially (and most likely) fire twice! Once for Async, and once again for Sync.
* It is important that you check event.isAsynchronous() and event.hasFiredAsync() to ensure you only act once.
- * If for some reason we are unable to send this asynchronously in the future, only the sync method will fire.
+ * If for some reason we are unable to send this asynchronously in the future, only the sync method will fire.
*
- * Your logic should look like this:
- * if (event.isAsynchronous() || !event.hasFiredAsync()) { do stuff }
+ * Your logic should look like this:
+ * {@code if (event.isAsynchronous() || !event.hasFiredAsync()) { // do stuff }}
*
- * If your logic is not safe to run asynchronously, only react to the synchronous version.
- * @deprecated Draft API - Subject to change until confirmed solves desired use cases
+ * If your logic is not safe to run asynchronously, only react to the synchronous version.
+ *
+ * This is a draft/experimental API and is subject to change.
*/
-@Deprecated
-@Warning(false)
+@ApiStatus.Experimental
public class AsyncPlayerSendCommandsEvent extends PlayerEvent {
private static final HandlerList handlers = new HandlerList();
@@ -43,14 +43,18 @@ public class AsyncPlayerSendCommandsEvent getCommandNode() {
return node;
}
/**
- * @return If this event has already fired asynchronously.
+ * Gets if this event has already fired asynchronously.
+ *
+ * @return whether this event has already fired asynchronously
*/
public boolean hasFiredAsync() {
return hasFiredAsync;
diff --git a/Paper-MojangAPI/src/main/java/com/destroystokyo/paper/event/brigadier/AsyncPlayerSendSuggestionsEvent.java b/Paper-MojangAPI/src/main/java/com/destroystokyo/paper/event/brigadier/AsyncPlayerSendSuggestionsEvent.java
index 13819b6185..4755ab24a6 100644
--- a/Paper-MojangAPI/src/main/java/com/destroystokyo/paper/event/brigadier/AsyncPlayerSendSuggestionsEvent.java
+++ b/Paper-MojangAPI/src/main/java/com/destroystokyo/paper/event/brigadier/AsyncPlayerSendSuggestionsEvent.java
@@ -10,8 +10,9 @@ import org.bukkit.event.player.PlayerEvent;
import org.jetbrains.annotations.NotNull;
/**
- * Called when sending Suggestions to the client. Will be called asynchronously if a plugin
- * marks the AsyncTabComplete event handled asynchronously, otherwise called synchronously.
+ * Called when sending {@link Suggestions} to the client. Will be called asynchronously if a plugin
+ * marks the {@link com.destroystokyo.paper.event.server.AsyncTabCompleteEvent} event handled asynchronously,
+ * otherwise called synchronously.
*/
public class AsyncPlayerSendSuggestionsEvent extends PlayerEvent implements Cancellable {
@@ -28,21 +29,27 @@ public class AsyncPlayerSendSuggestionsEvent extends PlayerEvent implements Canc
}
/**
- * @return The input buffer sent to request these suggestions
+ * Gets the input buffer sent to request these suggestions.
+ *
+ * @return the input buffer
*/
public String getBuffer() {
return buffer;
}
/**
- * @return The suggestions being sent to client
+ * Gets the suggestions to be sent to client.
+ *
+ * @return the suggestions
*/
public Suggestions getSuggestions() {
return suggestions;
}
/**
- * @param suggestions The suggestions to be sent to client if need to change them
+ * Sets the suggestions to be sent to client.
+ *
+ * @param suggestions suggestions
*/
public void setSuggestions(Suggestions suggestions) {
this.suggestions = suggestions;
@@ -57,7 +64,7 @@ public class AsyncPlayerSendSuggestionsEvent extends PlayerEvent implements Canc
}
/**
- * Cancels sending suggestions to the client
+ * Cancels sending suggestions to the client.
* {@inheritDoc}
*/
@Override
diff --git a/Paper-MojangAPI/src/main/java/com/destroystokyo/paper/event/brigadier/CommandRegisteredEvent.java b/Paper-MojangAPI/src/main/java/com/destroystokyo/paper/event/brigadier/CommandRegisteredEvent.java
index b7e09256a1..eb0409d816 100644
--- a/Paper-MojangAPI/src/main/java/com/destroystokyo/paper/event/brigadier/CommandRegisteredEvent.java
+++ b/Paper-MojangAPI/src/main/java/com/destroystokyo/paper/event/brigadier/CommandRegisteredEvent.java
@@ -5,24 +5,23 @@ import com.destroystokyo.paper.brigadier.BukkitBrigadierCommandSource;
import com.mojang.brigadier.tree.ArgumentCommandNode;
import com.mojang.brigadier.tree.LiteralCommandNode;
import com.mojang.brigadier.tree.RootCommandNode;
-import org.bukkit.Warning;
import org.bukkit.command.Command;
import org.bukkit.event.Cancellable;
import org.bukkit.event.HandlerList;
import org.bukkit.event.server.ServerEvent;
+import org.jetbrains.annotations.ApiStatus;
import org.jetbrains.annotations.NotNull;
/**
* Fired anytime the server synchronizes Bukkit commands to Brigadier.
*
- * Allows a plugin to control the command node structure for its commands.
+ * Allows a plugin to control the command node structure for its commands.
* This is done at Plugin Enable time after commands have been registered, but may also
- * run at a later point in the server lifetime due to plugins, a server reload, etc.
+ * run at a later point in the server lifetime due to plugins, a server reload, etc.
*
- * @deprecated Draft API - Subject to change until confirmed solves desired use cases
+ * This is a draft/experimental API and is subject to change.
*/
-@Deprecated
-@Warning(false)
+@ApiStatus.Experimental
public class CommandRegisteredEvent extends ServerEvent implements Cancellable {
private static final HandlerList handlers = new HandlerList();