Upstream/Paper
1
0
Fork 0
mirror of https://github.com/PaperMC/Paper.git synced 2024-12-27 03:17:36 +01:00
Code Issues Projects Releases Wiki Activity

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

Browse Source
This commit is contained in:
Jason Penilla 2022-08-07 13:47:43 -07:00
parent b9991242f3
commit 8667acbf07
3 changed files with 36 additions and 26 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

32
Paper-MojangAPI/src/main/java/com/destroystokyo/paper/event/brigadier/AsyncPlayerSendCommandsEvent.java
View File

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

19
Paper-MojangAPI/src/main/java/com/destroystokyo/paper/event/brigadier/AsyncPlayerSendSuggestionsEvent.java
View File

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

11
Paper-MojangAPI/src/main/java/com/destroystokyo/paper/event/brigadier/CommandRegisteredEvent.java
View File

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