Improve MojangAPI docs and replace @Deprecated with @ApiStatus.Experimental on draft APIs (#8261)

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.
+ * <p>This event may fire on login, world change, and permission rebuilds, by plugin request, and potentially future means.</p>
  *
- * This event will fire before {@link org.bukkit.event.player.PlayerCommandSendEvent}, so no filtering has been done by
- * other plugins yet.
+ * <p>This event will fire before {@link org.bukkit.event.player.PlayerCommandSendEvent}, so no filtering has been done by
+ * other plugins yet.</p>
  *
- * WARNING: This event will potentially (and most likely) fire twice! Once for Async, and once again for Sync.
+ * <p>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.</p>
  *
- * Your logic should look like this:
- * if (event.isAsynchronous() || !event.hasFiredAsync()) { do stuff }
+ * <p>Your logic should look like this:
+ * {@code if (event.isAsynchronous() || !event.hasFiredAsync()) { // do stuff }}</p>
  *
- * 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
+ * <p>If your logic is not safe to run asynchronously, only react to the synchronous version.</p>
+ *
+ * <p>This is a draft/experimental API and is subject to change.</p>
  */
-@Deprecated
-@Warning(false)
+@ApiStatus.Experimental
 public class AsyncPlayerSendCommandsEvent <S extends BukkitBrigadierCommandSource> extends PlayerEvent {
 
     private static final HandlerList handlers = new HandlerList();
@@ -43,14 +43,18 @@ public class AsyncPlayerSendCommandsEvent <S extends BukkitBrigadierCommandSourc
     }
 
     /**
-     * @return The full Root Command Node being sent to the client, which is mutable.
+     * Gets the full Root Command Node being sent to the client, which is mutable.
+     *
+     * @return the root command node
      */
     public RootCommandNode<S> 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;

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

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.
+ * <p>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.</p>
  *
- * @deprecated Draft API - Subject to change until confirmed solves desired use cases
+ * <p>This is a draft/experimental API and is subject to change.</p>
  */
-@Deprecated
-@Warning(false)
+@ApiStatus.Experimental
 public class CommandRegisteredEvent<S extends BukkitBrigadierCommandSource> extends ServerEvent implements Cancellable {
 
     private static final HandlerList handlers = new HandlerList();