Advertise the incrementProcessingDelay() function.

Discurage plugins of re-sending cancelled packets, as it makes it 
impossible for other plugins to take part in the processing.

Assume plugin A delays transmission of packet X by cancelling the event,
and then retransmitting X outside the filters. It is then impossible
for another plugin B to extend the delay without fighting plugin A
for control over the packet, for instance by decreasing the listener
priority and cancelling first.

It is much better for plugin A to call incrementProcessingDelay() in
an asynchronous listener. Then plugin B can do the same, and the
packet will be sent after both plugins has called
signalProcessingDone().

ProtocolLib/src/main/java/com/comphenix/protocol/AsynchronousManager.java

@@ -22,6 +22,7 @@ import java.util.Set;
 import org.bukkit.plugin.Plugin;
 
 import com.comphenix.protocol.async.AsyncListenerHandler;
+import com.comphenix.protocol.async.AsyncMarker;
 import com.comphenix.protocol.error.ErrorReporter;
 import com.comphenix.protocol.events.PacketEvent;
 import com.comphenix.protocol.events.PacketListener;
@@ -35,6 +36,8 @@ public interface AsynchronousManager {
 	/**
 	 * Registers an asynchronous packet handler.
 	 * <p>
+	 * Use {@link AsyncMarker#incrementProcessingDelay()} to delay a packet until its ready to be transmitted.
+	 * <p>
 	 * To start listening asynchronously, pass the getListenerLoop() runnable to a different thread.
 	 * @param listener - the packet listener that will recieve these asynchronous events.
 	 * @return An asynchrouns handler.

ProtocolLib/src/main/java/com/comphenix/protocol/async/AsyncFilterManager.java

@@ -43,7 +43,9 @@ import com.google.common.collect.Sets;
 
 /**
  * Represents a filter manager for asynchronous packets.
- * 
+ * <p>
+ * By using {@link AsyncMarker#incrementProcessingDelay()}, a packet can be delayed without having to block the
+ * processing thread.
  * @author Kristian
  */
 public class AsyncFilterManager implements AsynchronousManager {
@@ -128,6 +130,8 @@ public class AsyncFilterManager implements AsynchronousManager {
 	/**
 	 * Registers an asynchronous packet handler.
 	 * <p>
+	 * Use {@link AsyncMarker#incrementProcessingDelay()} to delay a packet until its ready to be transmitted.
+	 * <p>
 	 * To start listening asynchronously, pass the getListenerLoop() runnable to a different thread.
 	 * <p>
 	 * Asynchronous events will only be executed if a synchronous listener with the same packets is registered.

ProtocolLib/src/main/java/com/comphenix/protocol/async/AsyncListenerHandler.java

@@ -35,7 +35,8 @@ import com.google.common.base.Joiner;
 
 /**
  * Represents a handler for an asynchronous event.
- * 
+ * <p>
+ * Use {@link AsyncMarker#incrementProcessingDelay()} to delay a packet until a certain condition has been met.
  * @author Kristian
  */
 public class AsyncListenerHandler {

ProtocolLib/src/main/java/com/comphenix/protocol/async/AsyncMarker.java

@@ -206,7 +206,7 @@ public class AsyncMarker implements Serializable, Comparable<AsyncMarker> {
 	}
 
 	/**
-	 * Increment the number of times this packet must be signalled as done before its transmitted.
+	 * Increment the number of times the current packet must be signalled as done before its transmitted.
 	 * <p>
 	 * This is useful if an asynchronous listener is waiting for further information before the
 	 * packet can be sent to the user. A packet listener <b>MUST</b> eventually call 
@@ -215,9 +215,7 @@ public class AsyncMarker implements Serializable, Comparable<AsyncMarker> {
 	 * <p>
 	 * It is recommended that processing outside a packet listener is wrapped in a synchronized block 
 	 * using the {@link #getProcessingLock()} method.
-	 * <p>
+	 * 
-	 * To decrement the processing delay, call signalPacketUpdate. A thread that calls this method
-	 * multiple times must call signalPacketUpdate at least that many times.
 	 * @return The new processing delay.
 	 */
 	public int incrementProcessingDelay() {

ProtocolLib/src/main/java/com/comphenix/protocol/events/PacketEvent.java

@@ -134,7 +134,16 @@ public class PacketEvent extends EventObject implements Cancellable {
 	}
 
 	/**
-	 * Sets whether or not the packet should be cancelled.
+	 * Sets whether or not the packet should be cancelled. Uncancelling is possible.
+	 * <p>
+	 * <b>Warning</b>: A cancelled packet should never be re-transmitted. Use the asynchronous
+	 * packet manager if you need to perform extensive processing. It should also be used
+	 * if you need to synchronize with the main thread.
+	 * <p>
+	 * This ensures that other plugins can work with the same packet.
+	 * <p>
+	 * An asynchronous listener can also delay a packet indefinitely without having to block its thread.
+	 * 
 	 * @param cancel - TRUE if it should be cancelled, FALSE otherwise.
 	 */
 	public void setCancelled(boolean cancel) {