Improve docs coverage on event filters

Author: zml2008

src/main/java/org/spongepowered/api/event/filter/cause/package-info.java

@@ -22,5 +22,12 @@
  * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
  * THE SOFTWARE.
  */
+/**
+ * Cause-based <em>parameter source</em> annotations for event listeners.
+ *
+ * <p>These annotations extract information from the event's
+ * {@link org.spongepowered.api.event.Cause}, and if present pass that
+ * information to event listeners as method parameters.</p>
+ */
 @org.checkerframework.framework.qual.DefaultQualifier(org.checkerframework.checker.nullness.qual.NonNull.class)
 package org.spongepowered.api.event.filter.cause;

src/main/java/org/spongepowered/api/event/filter/data/GetValue.java

@@ -38,6 +38,10 @@
  *
  * <p>This value can be taken from the event cause's first {@link ValueContainer},
  * or any preceding parameter that inherits from {@link ValueContainer}.</p>
+ *
+ * <p>When looking for a value, searching will start from the parameter
+ * immediately before the annotated one, moving backwards and checking the first
+ * {@link ValueContainer} in the event cause last.</p>
  */
 @Target(ElementType.PARAMETER)
 @Retention(RetentionPolicy.RUNTIME)

src/main/java/org/spongepowered/api/event/filter/data/package-info.java

@@ -0,0 +1,33 @@
+/*
+ * This file is part of SpongeAPI, licensed under the MIT License (MIT).
+ *
+ * Copyright (c) SpongePowered <https://www.spongepowered.org>
+ * Copyright (c) contributors
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy
+ * of this software and associated documentation files (the "Software"), to deal
+ * in the Software without restriction, including without limitation the rights
+ * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+ * copies of the Software, and to permit persons to whom the Software is
+ * furnished to do so, subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in
+ * all copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+ * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+ * THE SOFTWARE.
+ */
+/**
+ * Event filter annotations working on
+ * {@link org.spongepowered.api.data.value.ValueContainer} parameters.
+ *
+ * <p>These annotations can be applied to existing parameters to filter based on
+ * data {@link org.spongepowered.api.data.Key}s.</p>
+ */
+@org.checkerframework.framework.qual.DefaultQualifier(org.checkerframework.checker.nullness.qual.NonNull.class)
+package org.spongepowered.api.event.filter.data;

src/main/java/org/spongepowered/api/event/filter/package-info.java

@@ -22,5 +22,12 @@
  * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
  * THE SOFTWARE.
  */
+/**
+ * Event filter annotations.
+ *
+ * <p>These annotations can be applied to event
+ * {@link org.spongepowered.api.event.Listener @Listener} methods to control
+ * which events are received and extract data from the event.</p>
+ */
 @org.checkerframework.framework.qual.DefaultQualifier(org.checkerframework.checker.nullness.qual.NonNull.class)
 package org.spongepowered.api.event.filter;

src/main/java/org/spongepowered/api/event/filter/type/package-info.java

@@ -22,5 +22,12 @@
  * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
  * THE SOFTWARE.
  */
+/**
+ * Listener method filters based on event type.
+ *
+ * <p>These annotations allow {@linkplain org.spongepowered.api.event.filter.type.Exclude excluding}
+ * and {@linkplain org.spongepowered.api.event.filter.type.Include including}
+ * subtypes of the declared event parameter in a declarative manner.</p>
+ */
 @org.checkerframework.framework.qual.DefaultQualifier(org.checkerframework.checker.nullness.qual.NonNull.class)
 package org.spongepowered.api.event.filter.type;