Document every event Velocity will await on.

api/src/main/java/com/velocitypowered/api/event/annotation/AwaitingEvent.java

@@ -0,0 +1,22 @@
+/*
+ * Copyright (C) 2018 Velocity Contributors
+ *
+ * The Velocity API is licensed under the terms of the MIT License. For more details,
+ * reference the LICENSE file in the api top-level directory.
+ */
+
+package com.velocitypowered.api.event.annotation;
+
+import java.lang.annotation.ElementType;
+import java.lang.annotation.Target;
+
+/**
+ * Marks an event as an event the proxy will wait on to completely fire (including any
+ * {@link com.velocitypowered.api.event.EventTask}s) before continuing handling it. Annotated
+ * classes are suitable candidates for using EventTasks for handling complex asynchronous
+ * operations in a non-blocking matter.
+ */
+@Target(ElementType.TYPE)
+public @interface AwaitingEvent {
+
+}

api/src/main/java/com/velocitypowered/api/event/command/CommandExecuteEvent.java

@@ -10,14 +10,17 @@
 import com.google.common.base.Preconditions;
 import com.velocitypowered.api.command.CommandSource;
 import com.velocitypowered.api.event.ResultedEvent;
+import com.velocitypowered.api.event.annotation.AwaitingEvent;
 import com.velocitypowered.api.event.command.CommandExecuteEvent.CommandResult;
 import java.util.Optional;
 import org.checkerframework.checker.nullness.qual.NonNull;
 import org.checkerframework.checker.nullness.qual.Nullable;
 
 /**
- * This event is fired when someone executing command.
+ * This event is fired when someone executes a command. Velocity will wait for this event to finish
+ * firing before trying to handle the command and/or forwarding it to the server.
  */
+@AwaitingEvent
 public final class CommandExecuteEvent implements ResultedEvent<CommandResult> {
 
   private final CommandSource commandSource;

api/src/main/java/com/velocitypowered/api/event/command/PlayerAvailableCommandsEvent.java

@@ -11,12 +11,16 @@
 
 import com.google.common.annotations.Beta;
 import com.mojang.brigadier.tree.RootCommandNode;
+import com.velocitypowered.api.event.annotation.AwaitingEvent;
 import com.velocitypowered.api.proxy.Player;
 
 /**
  * Allows plugins to modify the packet indicating commands available on the server to a
- * Minecraft 1.13+ client.
+ * Minecraft 1.13+ client. The given {@link RootCommandNode} is mutable. Velocity will wait
+ * for this event to finish firing before sending the list of available commands to the
+ * client.
  */
+@AwaitingEvent
 @Beta
 public class PlayerAvailableCommandsEvent {
 

api/src/main/java/com/velocitypowered/api/event/connection/ConnectionHandshakeEvent.java

@@ -12,6 +12,8 @@
 
 /**
  * This event is fired when a handshake is established between a client and the proxy.
+ * Velocity will fire this event asynchronously and will not wait for it to complete before
+ * handling the connection.
  */
 public final class ConnectionHandshakeEvent {
 

api/src/main/java/com/velocitypowered/api/event/connection/DisconnectEvent.java

@@ -8,12 +8,23 @@
 package com.velocitypowered.api.event.connection;
 
 import com.google.common.base.Preconditions;
+import com.velocitypowered.api.event.annotation.AwaitingEvent;
 import com.velocitypowered.api.proxy.Player;
 
 /**
- * This event is fired when a player disconnects from the proxy. Operations on the provided player,
- * aside from basic data retrieval operations, may behave in undefined ways.
+ * This event is fired when a player disconnects from the proxy. This operation can take place
+ * when the player disconnects due to normal network activity or when the proxy shuts down.
+ * Operations on the provided player, aside from basic data retrieval operations, may behave in
+ * undefined ways.
+ *
+ * <p>
+ *   Velocity typically fires this event asynchronously and does not wait for a response. However,
+ *   it will wait for all {@link DisconnectEvent}s for every player on the proxy to fire
+ *   successfully before the proxy shuts down. This event is the sole exception to the
+ *   {@link AwaitingEvent} contract.
+ * </p>
  */
+@AwaitingEvent
 public final class DisconnectEvent {
 
   private final Player player;

api/src/main/java/com/velocitypowered/api/event/connection/LoginEvent.java

@@ -9,12 +9,16 @@
 
 import com.google.common.base.Preconditions;
 import com.velocitypowered.api.event.ResultedEvent;
+import com.velocitypowered.api.event.annotation.AwaitingEvent;
 import com.velocitypowered.api.proxy.Player;
 
 /**
- * This event is fired once the player has been authenticated but before they connect to a server on
- * the proxy.
+ * This event is fired once the player has been authenticated, but before they connect to a server.
+ * Velocity will wait for this event to finish firing before proceeding with the rest of the login
+ * process, but you should try to limit the work done in any event that fires during the login
+ * process.
  */
+@AwaitingEvent
 public final class LoginEvent implements ResultedEvent<ResultedEvent.ComponentResult> {
 
   private final Player player;

api/src/main/java/com/velocitypowered/api/event/connection/PluginMessageEvent.java

@@ -11,6 +11,7 @@
 import com.google.common.io.ByteArrayDataInput;
 import com.google.common.io.ByteStreams;
 import com.velocitypowered.api.event.ResultedEvent;
+import com.velocitypowered.api.event.annotation.AwaitingEvent;
 import com.velocitypowered.api.proxy.Player;
 import com.velocitypowered.api.proxy.ServerConnection;
 import com.velocitypowered.api.proxy.messages.ChannelIdentifier;
@@ -21,8 +22,10 @@
 
 /**
  * This event is fired when a plugin message is sent to the proxy, either from a client ({@link
- * Player}) or a server ({@link ServerConnection}).
+ * Player}) or a server ({@link ServerConnection}). Velocity will wait on this event to finish
+ * firing before discarding the sent plugin message (if handled) or forwarding it to the server.
  */
+@AwaitingEvent
 public final class PluginMessageEvent implements ResultedEvent<PluginMessageEvent.ForwardResult> {
 
   private final ChannelMessageSource source;

api/src/main/java/com/velocitypowered/api/event/connection/PostLoginEvent.java

@@ -8,12 +8,17 @@
 package com.velocitypowered.api.event.connection;
 
 import com.google.common.base.Preconditions;
+import com.velocitypowered.api.event.annotation.AwaitingEvent;
 import com.velocitypowered.api.proxy.Player;
 
 /**
  * This event is fired once the player has been fully initialized and is about to connect to their
- * first server.
+ * first server. Velocity will wait for this event to finish firing before it fires
+ * {@link com.velocitypowered.api.event.player.PlayerChooseInitialServerEvent} with any default
+ * servers specified in the configuration, but you should try to limit the work done in any event
+ * that fires during the login process.
  */
+@AwaitingEvent
 public final class PostLoginEvent {
 
   private final Player player;

api/src/main/java/com/velocitypowered/api/event/connection/PreLoginEvent.java

@@ -9,6 +9,7 @@
 
 import com.google.common.base.Preconditions;
 import com.velocitypowered.api.event.ResultedEvent;
+import com.velocitypowered.api.event.annotation.AwaitingEvent;
 import com.velocitypowered.api.proxy.InboundConnection;
 import java.util.Optional;
 import org.checkerframework.checker.nullness.qual.NonNull;
@@ -17,8 +18,11 @@
 /**
  * This event is fired when a player has initiated a connection with the proxy but before the proxy
  * authenticates the player with Mojang or before the player's proxy connection is fully established
- * (for offline mode).
+ * (for offline mode). Velocity will wait for this event to finish firing before proceeding further
+ * with the login process, but you should try to limit the work done in any event that fires during
+ * the login process.
  */
+@AwaitingEvent
 public final class PreLoginEvent implements ResultedEvent<PreLoginEvent.PreLoginComponentResult> {
 
   private final InboundConnection connection;

api/src/main/java/com/velocitypowered/api/event/permission/PermissionsSetupEvent.java

@@ -8,16 +8,26 @@
 package com.velocitypowered.api.event.permission;
 
 import com.google.common.base.Preconditions;
+import com.velocitypowered.api.event.annotation.AwaitingEvent;
 import com.velocitypowered.api.permission.PermissionFunction;
 import com.velocitypowered.api.permission.PermissionProvider;
 import com.velocitypowered.api.permission.PermissionSubject;
 import org.checkerframework.checker.nullness.qual.Nullable;
 
 /**
- * Called when a {@link PermissionSubject}'s permissions are being setup.
+ * Called when a {@link PermissionSubject}'s permissions are being setup. This event is typically
+ * called for the {@link com.velocitypowered.api.proxy.ConsoleCommandSource} and any
+ * {@link com.velocitypowered.api.proxy.Player}s who join the proxy.
  *
  * <p>This event is only called once per subject, on initialisation.</p>
+ *
+ * <p>
+ *   Velocity will wait for this event to finish firing before proceeding further with server
+ *   startup (for the console command source) and logins (for players) but it is strongly
+ *   recommended to minimize the amount of work that must be done in this event.
+ * </p>
  */
+@AwaitingEvent
 public final class PermissionsSetupEvent {
 
   private final PermissionSubject subject;

api/src/main/java/com/velocitypowered/api/event/player/GameProfileRequestEvent.java

@@ -8,6 +8,7 @@
 package com.velocitypowered.api.event.player;
 
 import com.google.common.base.Preconditions;
+import com.velocitypowered.api.event.annotation.AwaitingEvent;
 import com.velocitypowered.api.proxy.InboundConnection;
 import com.velocitypowered.api.util.GameProfile;
 import org.checkerframework.checker.nullness.qual.Nullable;
@@ -16,7 +17,14 @@
  * This event is fired after the {@link com.velocitypowered.api.event.connection.PreLoginEvent} in
  * order to set up the game profile for the user. This can be used to configure a custom profile for
  * a user, i.e. skin replacement.
+ *
+ * <p>
+ *   Velocity will wait for this event to finish firing before proceeding with the rest of the login
+ *   process, but you should try to limit the work done in any event that fires during the login
+ *   process.
+ * </p>
  */
+@AwaitingEvent
 public final class GameProfileRequestEvent {
 
   private final String username;

api/src/main/java/com/velocitypowered/api/event/player/KickedFromServerEvent.java

@@ -9,6 +9,7 @@
 
 import com.google.common.base.Preconditions;
 import com.velocitypowered.api.event.ResultedEvent;
+import com.velocitypowered.api.event.annotation.AwaitingEvent;
 import com.velocitypowered.api.proxy.Player;
 import com.velocitypowered.api.proxy.server.RegisteredServer;
 import java.util.Optional;
@@ -19,8 +20,10 @@
  * Fired when a player is kicked from a server. You may either allow Velocity to kick the player
  * (with an optional reason override) or redirect the player to a separate server. By default,
  * Velocity will notify the user (if they are already connected to a server) or disconnect them
- * (if they are not on a server and no other servers are available).
+ * (if they are not on a server and no other servers are available). Velocity will wait on this
+ * event to finish firing before taking the specified action.
  */
+@AwaitingEvent
 public final class KickedFromServerEvent implements
     ResultedEvent<KickedFromServerEvent.ServerKickResult> {
 

api/src/main/java/com/velocitypowered/api/event/player/PlayerChannelRegisterEvent.java

@@ -15,7 +15,7 @@
 
 /**
  * This event is fired when a client ({@link Player}) sends a plugin message through the
- * register channel.
+ * register channel. Velocity will not wait on this event to finish firing.
  */
 public final class PlayerChannelRegisterEvent {
 

api/src/main/java/com/velocitypowered/api/event/player/PlayerChatEvent.java

@@ -9,14 +9,17 @@
 
 import com.google.common.base.Preconditions;
 import com.velocitypowered.api.event.ResultedEvent;
+import com.velocitypowered.api.event.annotation.AwaitingEvent;
 import com.velocitypowered.api.proxy.Player;
 import java.util.Optional;
 import org.checkerframework.checker.nullness.qual.NonNull;
 import org.checkerframework.checker.nullness.qual.Nullable;
 
 /**
- * This event is fired when a player types in a chat message.
+ * This event is fired when a player types in a chat message. Velocity will wait on this event
+ * to finish firing before forwarding it to the server, if the result allows it.
  */
+@AwaitingEvent
 public final class PlayerChatEvent implements ResultedEvent<PlayerChatEvent.ChatResult> {
 
   private final Player player;

api/src/main/java/com/velocitypowered/api/event/player/PlayerChooseInitialServerEvent.java

@@ -8,15 +8,19 @@
 package com.velocitypowered.api.event.player;
 
 import com.google.common.base.Preconditions;
+import com.velocitypowered.api.event.annotation.AwaitingEvent;
 import com.velocitypowered.api.proxy.Player;
 import com.velocitypowered.api.proxy.server.RegisteredServer;
 import java.util.Optional;
 import org.checkerframework.checker.nullness.qual.Nullable;
 
 /**
- * Fired when a player has finished connecting to the proxy and we need to choose the first server
- * to connect to.
+ * Fired when a player has finished the login process, and we need to choose the first server
+ * to connect to. Velocity will wait on this event to finish firing before initiating the connection
+ * but you should try to limit the work done in this event. Failures will be handled by
+ * {@link KickedFromServerEvent} as normal.
  */
+@AwaitingEvent
 public class PlayerChooseInitialServerEvent {
 
   private final Player player;

api/src/main/java/com/velocitypowered/api/event/player/PlayerClientBrandEvent.java

@@ -11,7 +11,8 @@
 import com.velocitypowered.api.proxy.Player;
 
 /**
- * Fired when a {@link Player} sends the <code>minecraft:brand</code> plugin message.
+ * Fired when a {@link Player} sends the <code>minecraft:brand</code> plugin message. Velocity will
+ * not wait on the result of this event.
  */
 public final class PlayerClientBrandEvent {
   private final Player player;

api/src/main/java/com/velocitypowered/api/event/player/PlayerModInfoEvent.java

@@ -14,6 +14,7 @@
 
 /**
  * This event is fired when a Forge client sends its mods to the proxy while connecting to a server.
+ * Velocity will not wait on this event to finish firing.
  */
 public final class PlayerModInfoEvent {
 

api/src/main/java/com/velocitypowered/api/event/player/PlayerResourcePackStatusEvent.java

@@ -8,6 +8,7 @@
 package com.velocitypowered.api.event.player;
 
 import com.google.common.base.Preconditions;
+import com.velocitypowered.api.event.annotation.AwaitingEvent;
 import com.velocitypowered.api.network.ProtocolVersion;
 import com.velocitypowered.api.proxy.Player;
 import com.velocitypowered.api.proxy.player.ResourcePackInfo;
@@ -16,16 +17,17 @@
 
 /**
  * This event is fired when the status of a resource pack sent to the player by the server is
- * changed.
+ * changed. Depending on the result of this event (which Velocity will wait until completely fired),
+ * the player may be kicked from the server.
  */
+@AwaitingEvent
 public class PlayerResourcePackStatusEvent {
 
   private final Player player;
   private final Status status;
   private final @MonotonicNonNull ResourcePackInfo packInfo;
   private boolean overwriteKick;
 
-
   /**
    * Instantiates this event.
    * @deprecated Use {@link PlayerResourcePackStatusEvent#PlayerResourcePackStatusEvent

api/src/main/java/com/velocitypowered/api/event/player/PlayerSettingsChangedEvent.java

@@ -12,6 +12,11 @@
 import com.velocitypowered.api.proxy.Player;
 import com.velocitypowered.api.proxy.player.PlayerSettings;
 
+/**
+ * This event is fired when the client sends new client settings for the player. This event can
+ * and typically will be fired multiple times per connection. Velocity will not wait on this event
+ * to finish firing.
+ */
 public final class PlayerSettingsChangedEvent {
 
   private final Player player;

api/src/main/java/com/velocitypowered/api/event/player/ServerConnectedEvent.java

@@ -8,6 +8,7 @@
 package com.velocitypowered.api.event.player;
 
 import com.google.common.base.Preconditions;
+import com.velocitypowered.api.event.annotation.AwaitingEvent;
 import com.velocitypowered.api.proxy.Player;
 import com.velocitypowered.api.proxy.server.RegisteredServer;
 import java.util.Optional;
@@ -16,7 +17,14 @@
 /**
  * This event is fired once the player has successfully connected to the target server and the
  * connection to the previous server has been de-established.
+ *
+ * <p>
+ *   <strong>Note</strong>: For historical reasons, Velocity does wait on this event to finish
+ *   firing before continuing the server connection process. This behavior is
+ *   <strong>deprecated</strong> and likely to be removed in Polymer.
+ * </p>
  */
+@AwaitingEvent
 public final class ServerConnectedEvent {
 
   private final Player player;

api/src/main/java/com/velocitypowered/api/event/player/ServerLoginPluginMessageEvent.java

@@ -13,6 +13,7 @@
 import com.google.common.io.ByteArrayDataInput;
 import com.google.common.io.ByteStreams;
 import com.velocitypowered.api.event.ResultedEvent;
+import com.velocitypowered.api.event.annotation.AwaitingEvent;
 import com.velocitypowered.api.event.player.ServerLoginPluginMessageEvent.ResponseResult;
 import com.velocitypowered.api.proxy.ServerConnection;
 import com.velocitypowered.api.proxy.messages.ChannelIdentifier;
@@ -22,8 +23,11 @@
 
 /**
  * Fired when a server sends a login plugin message to the proxy. Plugins have the opportunity to
- * respond to the messages as needed.
+ * respond to the messages as needed. Velocity will wait on this event to finish. The server will
+ * be responsible for continuing the login process once the server is satisfied with any login
+ * plugin responses sent by proxy plugins (or messages indicating a lack of response).
  */
+@AwaitingEvent
 public class ServerLoginPluginMessageEvent implements ResultedEvent<ResponseResult> {
   private final ServerConnection connection;
   private final ChannelIdentifier identifier;