SPIGOT-4487: Clarify PlayerInteractEvent docs

1 files changed, 7 insertions, 2 deletions

diff --git a/src/main/java/org/bukkit/event/player/PlayerInteractEvent.java b/src/main/java/org/bukkit/event/player/PlayerInteractEvent.java
index 0c841fb1..fdad4cd3 100644
--- a/src/main/java/org/bukkit/event/player/PlayerInteractEvent.java
+++ b/src/main/java/org/bukkit/event/player/PlayerInteractEvent.java
@@ -8,6 +8,7 @@ import org.bukkit.Material;
 import org.bukkit.entity.Player;
 import org.bukkit.event.Cancellable;
 import org.bukkit.event.block.Action;
+import org.bukkit.event.block.BlockCanBuildEvent;
 import org.bukkit.inventory.EquipmentSlot;
 
 /**
@@ -15,8 +16,12 @@ import org.bukkit.inventory.EquipmentSlot;
  * air, potentially fired once for each hand. The hand can be determined using
  * {@link #getHand()}.
  * <p>
- * This event will fire as cancelled if the vanilla behavior
- * is to do nothing (e.g interacting with air)
+ * This event will fire as cancelled if the vanilla behavior is to do nothing
+ * (e.g interacting with air). For the purpose of avoiding doubt, this means
+ * that the event will only be in the cancelled state if it is fired as a result
+ * of some prediction made by the server where no subsequent code will run,
+ * rather than when the subsequent interaction activity (e.g. placing a block in
+ * an illegal position ({@link BlockCanBuildEvent}) will fail.
  */
 public class PlayerInteractEvent extends PlayerEvent implements Cancellable {
     private static final HandlerList handlers = new HandlerList();