Add javadocs for NotifyNeighborBlockEvent

Author: aromaa

src/main/java/org/spongepowered/api/block/transaction/NotificationTicket.java

@@ -28,24 +28,60 @@
 import org.spongepowered.api.world.LocatableBlock;
 import org.spongepowered.math.vector.Vector3i;
 
+/**
+ * Represents a notification that is being proposed to the engine.
+ */
 public interface NotificationTicket {
 
+    /**
+     * Gets the notifier block that scheduled this notification.
+     *
+     * @return The notifier block
+     */
     LocatableBlock notifier();
 
+    /**
+     * Gets the notifier position that scheduled this notification.
+     *
+     * @return The notifier position
+     */
     default Vector3i notifierPosition() {
         return this.notifier().blockPosition();
     }
 
+    /**
+     * Gets the target block of this notification.
+     *
+     * @return The target block
+     */
     BlockSnapshot target();
 
+    /**
+     * Gets the target position of this notification.
+     *
+     * @return The target position
+     */
     default Vector3i targetPosition() {
         return this.target().position();
     }
 
+    /**
+     * Gets whether this ticket is marked as valid.
+     *
+     * @return The valid state of this ticket
+     */
     boolean valid();
 
+    /**
+     * Sets whether this ticket is valid or not.
+     *
+     * @param valid The valid state of this ticket
+     */
     void setValid(boolean valid);
 
+    /**
+     * Invalidates this ticket.
+     */
     default void invalidate() {
         this.setValid(false);
     }

src/main/java/org/spongepowered/api/event/block/NotifyNeighborBlockEvent.java

@@ -33,12 +33,30 @@
 import java.util.function.Predicate;
 
 /**
- *
+ * Fired when a neighbour notification is being proposed to the engine.
  */
 public interface NotifyNeighborBlockEvent extends Event, Cancellable {
 
+    /**
+     * Gets a list of the {@link NotificationTicket}s for this event.
+     * If a ticket is requested to be marked as "invalid",
+     * {@link NotificationTicket#setValid(boolean)} can be used.
+     *
+     * @return The unmodifiable list of tickets
+     */
     List<NotificationTicket> tickets();
 
+    /**
+     * Applies the provided {@link Predicate} to the {@link List} of
+     * {@link NotificationTicket}s from {@link #tickets()} such that
+     * any time that {@link Predicate#test(Object)} returns {@code false}
+     * on the location of the {@link NotificationTicket}, the
+     * {@link NotificationTicket} is marked as "invalid".
+     *
+     * <p>{@link NotificationTicket#targetPosition()} is used to get the {@link Vector3i}</p>
+     *
+     * @param predicate The predicate to use for filtering
+     */
     default void filterTargetPositions(final Predicate<Vector3i> predicate) {
         this.tickets().forEach(ticket -> {
             if (!predicate.test(ticket.targetPosition())) {
@@ -47,6 +65,15 @@ default void filterTargetPositions(final Predicate<Vector3i> predicate) {
         });
     }
 
+    /**
+     * Applies the provided {@link Predicate} to the {@link List} of
+     * {@link NotificationTicket}s from {@link #tickets()} such that
+     * any time that {@link Predicate#test(Object)} returns {@code false}
+     * on the location of the {@link NotificationTicket}, the
+     * {@link NotificationTicket} is marked as "invalid".
+     *
+     * @param predicate The predicate to use for filtering
+     */
     default void filterTickets(final Predicate<NotificationTicket> predicate) {
         this.tickets().forEach(ticket -> {
             if (!predicate.test(ticket)) {