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

This commit is contained in:
Jason 2022-08-07 13:47:43 -07:00 committed by GitHub
parent a15152e96a
commit 0118c0bd79
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
3 changed files with 36 additions and 26 deletions

View File

@ -3,33 +3,33 @@ package com.destroystokyo.paper.event.brigadier;
import com.destroystokyo.paper.brigadier.BukkitBrigadierCommandSource; import com.destroystokyo.paper.brigadier.BukkitBrigadierCommandSource;
import com.mojang.brigadier.tree.RootCommandNode; import com.mojang.brigadier.tree.RootCommandNode;
import org.bukkit.Bukkit; import org.bukkit.Bukkit;
import org.bukkit.Warning;
import org.bukkit.entity.Player; import org.bukkit.entity.Player;
import org.bukkit.event.HandlerList; import org.bukkit.event.HandlerList;
import org.bukkit.event.player.PlayerEvent; import org.bukkit.event.player.PlayerEvent;
import org.jetbrains.annotations.ApiStatus;
import org.jetbrains.annotations.NotNull; import org.jetbrains.annotations.NotNull;
/** /**
* Fired any time a Brigadier RootCommandNode is generated for a player to inform the client of commands. * 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. * 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 * <p>This event will fire before {@link org.bukkit.event.player.PlayerCommandSendEvent}, so no filtering has been done by
* other plugins yet. * 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. * 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: * <p>Your logic should look like this:
* if (event.isAsynchronous() || !event.hasFiredAsync()) { do stuff } * {@code if (event.isAsynchronous() || !event.hasFiredAsync()) { // do stuff }}</p>
* *
* If your logic is not safe to run asynchronously, only react to the synchronous version. * <p>If your logic is not safe to run asynchronously, only react to the synchronous version.</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 @ApiStatus.Experimental
@Warning(false)
public class AsyncPlayerSendCommandsEvent <S extends BukkitBrigadierCommandSource> extends PlayerEvent { public class AsyncPlayerSendCommandsEvent <S extends BukkitBrigadierCommandSource> extends PlayerEvent {
private static final HandlerList handlers = new HandlerList(); 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() { public RootCommandNode<S> getCommandNode() {
return node; 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() { public boolean hasFiredAsync() {
return hasFiredAsync; return hasFiredAsync;

View File

@ -10,8 +10,9 @@ import org.bukkit.event.player.PlayerEvent;
import org.jetbrains.annotations.NotNull; import org.jetbrains.annotations.NotNull;
/** /**
* Called when sending Suggestions to the client. Will be called asynchronously if a plugin * Called when sending {@link Suggestions} to the client. Will be called asynchronously if a plugin
* marks the AsyncTabComplete event handled asynchronously, otherwise called synchronously. * marks the {@link com.destroystokyo.paper.event.server.AsyncTabCompleteEvent} event handled asynchronously,
* otherwise called synchronously.
*/ */
public class AsyncPlayerSendSuggestionsEvent extends PlayerEvent implements Cancellable { 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() { public String getBuffer() {
return buffer; return buffer;
} }
/** /**
* @return The suggestions being sent to client * Gets the suggestions to be sent to client.
*
* @return the suggestions
*/ */
public Suggestions getSuggestions() { public Suggestions getSuggestions() {
return suggestions; 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) { public void setSuggestions(Suggestions suggestions) {
this.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} * {@inheritDoc}
*/ */
@Override @Override

View File

@ -5,24 +5,23 @@ import com.destroystokyo.paper.brigadier.BukkitBrigadierCommandSource;
import com.mojang.brigadier.tree.ArgumentCommandNode; import com.mojang.brigadier.tree.ArgumentCommandNode;
import com.mojang.brigadier.tree.LiteralCommandNode; import com.mojang.brigadier.tree.LiteralCommandNode;
import com.mojang.brigadier.tree.RootCommandNode; import com.mojang.brigadier.tree.RootCommandNode;
import org.bukkit.Warning;
import org.bukkit.command.Command; import org.bukkit.command.Command;
import org.bukkit.event.Cancellable; import org.bukkit.event.Cancellable;
import org.bukkit.event.HandlerList; import org.bukkit.event.HandlerList;
import org.bukkit.event.server.ServerEvent; import org.bukkit.event.server.ServerEvent;
import org.jetbrains.annotations.ApiStatus;
import org.jetbrains.annotations.NotNull; import org.jetbrains.annotations.NotNull;
/** /**
* Fired anytime the server synchronizes Bukkit commands to Brigadier. * 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 * 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 @ApiStatus.Experimental
@Warning(false)
public class CommandRegisteredEvent<S extends BukkitBrigadierCommandSource> extends ServerEvent implements Cancellable { public class CommandRegisteredEvent<S extends BukkitBrigadierCommandSource> extends ServerEvent implements Cancellable {
private static final HandlerList handlers = new HandlerList(); private static final HandlerList handlers = new HandlerList();