From 7ab4a283fe10b1b05f1e492a21e47a5dc939ac59 Mon Sep 17 00:00:00 2001
From: sk89q <the.sk89q@gmail.com>
Date: Sun, 31 Aug 2014 16:10:04 -0700
Subject: [PATCH] Document the delegate events.

Fixes WORLDGUARD-3164.
---
 .../com/sk89q/worldguard/bukkit/event/DelegateEvent.java   | 4 ++++
 .../com/sk89q/worldguard/bukkit/event/DelegateEvents.java  | 3 +++
 .../worldguard/bukkit/event/block/AbstractBlockEvent.java  | 4 ++++
 .../worldguard/bukkit/event/block/BreakBlockEvent.java     | 6 ++++++
 .../worldguard/bukkit/event/block/PlaceBlockEvent.java     | 6 ++++++
 .../sk89q/worldguard/bukkit/event/block/UseBlockEvent.java | 5 ++++-
 .../bukkit/event/entity/AbstractEntityEvent.java           | 4 ++++
 .../worldguard/bukkit/event/entity/DamageEntityEvent.java  | 6 ++++++
 .../worldguard/bukkit/event/entity/DestroyEntityEvent.java | 6 ++++++
 .../worldguard/bukkit/event/entity/SpawnEntityEvent.java   | 6 ++++++
 .../worldguard/bukkit/event/entity/UseEntityEvent.java     | 5 ++++-
 .../worldguard/bukkit/event/inventory/UseItemEvent.java    | 5 ++++-
 .../worldguard/bukkit/event/player/ProcessPlayerEvent.java | 7 +++++++
 13 files changed, 64 insertions(+), 3 deletions(-)

diff --git a/src/main/java/com/sk89q/worldguard/bukkit/event/DelegateEvent.java b/src/main/java/com/sk89q/worldguard/bukkit/event/DelegateEvent.java
index 0415da58..5fcb72b2 100644
--- a/src/main/java/com/sk89q/worldguard/bukkit/event/DelegateEvent.java
+++ b/src/main/java/com/sk89q/worldguard/bukkit/event/DelegateEvent.java
@@ -27,6 +27,10 @@
 
 import static com.google.common.base.Preconditions.checkNotNull;
 
+/**
+ * This event is an internal event. We do not recommend handling or throwing
+ * this event or its subclasses as the interface is highly subject to change.
+ */
 public abstract class DelegateEvent extends Event implements Cancellable {
 
     @Nullable
diff --git a/src/main/java/com/sk89q/worldguard/bukkit/event/DelegateEvents.java b/src/main/java/com/sk89q/worldguard/bukkit/event/DelegateEvents.java
index c43119f7..d526e129 100644
--- a/src/main/java/com/sk89q/worldguard/bukkit/event/DelegateEvents.java
+++ b/src/main/java/com/sk89q/worldguard/bukkit/event/DelegateEvents.java
@@ -19,6 +19,9 @@
 
 package com.sk89q.worldguard.bukkit.event;
 
+/**
+ * Utility methods for dealing with delegate events.
+ */
 public final class DelegateEvents {
 
     private DelegateEvents() {
diff --git a/src/main/java/com/sk89q/worldguard/bukkit/event/block/AbstractBlockEvent.java b/src/main/java/com/sk89q/worldguard/bukkit/event/block/AbstractBlockEvent.java
index 18715f4e..7a3a52c4 100644
--- a/src/main/java/com/sk89q/worldguard/bukkit/event/block/AbstractBlockEvent.java
+++ b/src/main/java/com/sk89q/worldguard/bukkit/event/block/AbstractBlockEvent.java
@@ -36,6 +36,10 @@
 
 import static com.google.common.base.Preconditions.checkNotNull;
 
+/**
+ * This event is an internal event. We do not recommend handling or throwing
+ * this event or its subclasses as the interface is highly subject to change.
+ */
 abstract class AbstractBlockEvent extends DelegateEvent implements BulkEvent {
 
     private final World world;
diff --git a/src/main/java/com/sk89q/worldguard/bukkit/event/block/BreakBlockEvent.java b/src/main/java/com/sk89q/worldguard/bukkit/event/block/BreakBlockEvent.java
index f5cc3088..2f039a62 100644
--- a/src/main/java/com/sk89q/worldguard/bukkit/event/block/BreakBlockEvent.java
+++ b/src/main/java/com/sk89q/worldguard/bukkit/event/block/BreakBlockEvent.java
@@ -30,6 +30,12 @@
 import javax.annotation.Nullable;
 import java.util.List;
 
+/**
+ * This event is an internal event. We do not recommend handling or throwing
+ * this event or its subclasses as the interface is highly subject to change.
+ *
+ * <p>Thrown when a block is broken.</p>
+ */
 public class BreakBlockEvent extends AbstractBlockEvent {
 
     private static final HandlerList handlers = new HandlerList();
diff --git a/src/main/java/com/sk89q/worldguard/bukkit/event/block/PlaceBlockEvent.java b/src/main/java/com/sk89q/worldguard/bukkit/event/block/PlaceBlockEvent.java
index ea8f1d49..20a28365 100644
--- a/src/main/java/com/sk89q/worldguard/bukkit/event/block/PlaceBlockEvent.java
+++ b/src/main/java/com/sk89q/worldguard/bukkit/event/block/PlaceBlockEvent.java
@@ -30,6 +30,12 @@
 import javax.annotation.Nullable;
 import java.util.List;
 
+/**
+ * This event is an internal event. We do not recommend handling or throwing
+ * this event or its subclasses as the interface is highly subject to change.
+ *
+ * <p>Thrown when a block is placed.</p>
+ */
 public class PlaceBlockEvent extends AbstractBlockEvent {
 
     private static final HandlerList handlers = new HandlerList();
diff --git a/src/main/java/com/sk89q/worldguard/bukkit/event/block/UseBlockEvent.java b/src/main/java/com/sk89q/worldguard/bukkit/event/block/UseBlockEvent.java
index 921043ed..31d17c24 100644
--- a/src/main/java/com/sk89q/worldguard/bukkit/event/block/UseBlockEvent.java
+++ b/src/main/java/com/sk89q/worldguard/bukkit/event/block/UseBlockEvent.java
@@ -31,7 +31,10 @@
 import java.util.List;
 
 /**
- * Fired when a block is interacted with.
+ * This event is an internal event. We do not recommend handling or throwing
+ * this event or its subclasses as the interface is highly subject to change.
+ *
+ * <p>Thrown when a block is interacted with.</p>
  */
 public class UseBlockEvent extends AbstractBlockEvent {
 
diff --git a/src/main/java/com/sk89q/worldguard/bukkit/event/entity/AbstractEntityEvent.java b/src/main/java/com/sk89q/worldguard/bukkit/event/entity/AbstractEntityEvent.java
index 5bed78fa..ee0b96c5 100644
--- a/src/main/java/com/sk89q/worldguard/bukkit/event/entity/AbstractEntityEvent.java
+++ b/src/main/java/com/sk89q/worldguard/bukkit/event/entity/AbstractEntityEvent.java
@@ -31,6 +31,10 @@
 
 import static com.google.common.base.Preconditions.checkNotNull;
 
+/**
+ * This event is an internal event. We do not recommend handling or throwing
+ * this event or its subclasses as the interface is highly subject to change.
+ */
 abstract class AbstractEntityEvent extends DelegateEvent {
 
     private final Location target;
diff --git a/src/main/java/com/sk89q/worldguard/bukkit/event/entity/DamageEntityEvent.java b/src/main/java/com/sk89q/worldguard/bukkit/event/entity/DamageEntityEvent.java
index 1a56d500..cef3342b 100644
--- a/src/main/java/com/sk89q/worldguard/bukkit/event/entity/DamageEntityEvent.java
+++ b/src/main/java/com/sk89q/worldguard/bukkit/event/entity/DamageEntityEvent.java
@@ -29,6 +29,12 @@
 
 import static com.google.common.base.Preconditions.checkNotNull;
 
+/**
+ * This event is an internal event. We do not recommend handling or throwing
+ * this event or its subclasses as the interface is highly subject to change.
+ *
+ * <p>Thrown when an entity is damaged.</p>
+ */
 public class DamageEntityEvent extends AbstractEntityEvent {
 
     private static final HandlerList handlers = new HandlerList();
diff --git a/src/main/java/com/sk89q/worldguard/bukkit/event/entity/DestroyEntityEvent.java b/src/main/java/com/sk89q/worldguard/bukkit/event/entity/DestroyEntityEvent.java
index fd2d4056..bcf744d9 100644
--- a/src/main/java/com/sk89q/worldguard/bukkit/event/entity/DestroyEntityEvent.java
+++ b/src/main/java/com/sk89q/worldguard/bukkit/event/entity/DestroyEntityEvent.java
@@ -29,6 +29,12 @@
 
 import static com.google.common.base.Preconditions.checkNotNull;
 
+/**
+ * This event is an internal event. We do not recommend handling or throwing
+ * this event or its subclasses as the interface is highly subject to change.
+ *
+ * <p>Thrown when an entity is removed.</p>
+ */
 public class DestroyEntityEvent extends AbstractEntityEvent {
 
     private static final HandlerList handlers = new HandlerList();
diff --git a/src/main/java/com/sk89q/worldguard/bukkit/event/entity/SpawnEntityEvent.java b/src/main/java/com/sk89q/worldguard/bukkit/event/entity/SpawnEntityEvent.java
index 00817798..0228024a 100644
--- a/src/main/java/com/sk89q/worldguard/bukkit/event/entity/SpawnEntityEvent.java
+++ b/src/main/java/com/sk89q/worldguard/bukkit/event/entity/SpawnEntityEvent.java
@@ -30,6 +30,12 @@
 
 import static com.google.common.base.Preconditions.checkNotNull;
 
+/**
+ * This event is an internal event. We do not recommend handling or throwing
+ * this event or its subclasses as the interface is highly subject to change.
+ *
+ * <p>Thrown when an entity is spawned.</p>
+ */
 public class SpawnEntityEvent extends AbstractEntityEvent {
 
     private static final HandlerList handlers = new HandlerList();
diff --git a/src/main/java/com/sk89q/worldguard/bukkit/event/entity/UseEntityEvent.java b/src/main/java/com/sk89q/worldguard/bukkit/event/entity/UseEntityEvent.java
index 9df27960..c54a9fcd 100644
--- a/src/main/java/com/sk89q/worldguard/bukkit/event/entity/UseEntityEvent.java
+++ b/src/main/java/com/sk89q/worldguard/bukkit/event/entity/UseEntityEvent.java
@@ -30,7 +30,10 @@
 import static com.google.common.base.Preconditions.checkNotNull;
 
 /**
- * Fired when an entity is interacted with.
+ * This event is an internal event. We do not recommend handling or throwing
+ * this event or its subclasses as the interface is highly subject to change.
+ *
+ * <p>Thrown when an entity is used.</p>
  */
 public class UseEntityEvent extends AbstractEntityEvent {
 
diff --git a/src/main/java/com/sk89q/worldguard/bukkit/event/inventory/UseItemEvent.java b/src/main/java/com/sk89q/worldguard/bukkit/event/inventory/UseItemEvent.java
index e5311148..d387e00f 100644
--- a/src/main/java/com/sk89q/worldguard/bukkit/event/inventory/UseItemEvent.java
+++ b/src/main/java/com/sk89q/worldguard/bukkit/event/inventory/UseItemEvent.java
@@ -31,7 +31,10 @@
 import static com.google.common.base.Preconditions.checkNotNull;
 
 /**
- * Fired when an item is interacted with.
+ * This event is an internal event. We do not recommend handling or throwing
+ * this event or its subclasses as the interface is highly subject to change.
+ *
+ * <p>Thrown when an item is used.</p>
  */
 public class UseItemEvent extends DelegateEvent {
 
diff --git a/src/main/java/com/sk89q/worldguard/bukkit/event/player/ProcessPlayerEvent.java b/src/main/java/com/sk89q/worldguard/bukkit/event/player/ProcessPlayerEvent.java
index 7a540838..af50ae4e 100644
--- a/src/main/java/com/sk89q/worldguard/bukkit/event/player/ProcessPlayerEvent.java
+++ b/src/main/java/com/sk89q/worldguard/bukkit/event/player/ProcessPlayerEvent.java
@@ -25,6 +25,13 @@
 
 import static com.google.common.base.Preconditions.checkNotNull;
 
+/**
+ * This event is an internal event. We do not recommend handling or throwing
+ * this event or its subclasses as the interface is highly subject to change.
+ *
+ * <p>Posted when a player has to be processed, either because a world has been
+ * loaded, the server has started, or WorldGuard has been reloaded.</p>
+ */
 public class ProcessPlayerEvent extends Event {
 
     private static final HandlerList handlers = new HandlerList();