cleanup and javadoc

cloud-paper/src/main/java/org/incendo/cloud/paper/sender/ConsoleSource.java → cloud-paper/src/main/java/org/incendo/cloud/paper/util/sender/ConsoleSource.java

@@ -21,12 +21,16 @@
 // OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
 // SOFTWARE.
 //
-package org.incendo.cloud.paper.sender;
+package org.incendo.cloud.paper.util.sender;
 
 import io.papermc.paper.command.brigadier.CommandSourceStack;
 import org.bukkit.command.ConsoleCommandSender;
 import org.checkerframework.checker.nullness.qual.NonNull;
 
+/**
+ * Specialized variant of {@link Source}, for when the {@link CommandSourceStack#getSender() sender} is a
+ * {@link ConsoleCommandSender}.
+ */
 @SuppressWarnings("UnstableApiUsage")
 public final class ConsoleSource extends GenericSource {
 

cloud-paper/src/main/java/org/incendo/cloud/paper/sender/EntitySource.java → cloud-paper/src/main/java/org/incendo/cloud/paper/util/sender/EntitySource.java

@@ -21,19 +21,28 @@
 // OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
 // SOFTWARE.
 //
-package org.incendo.cloud.paper.sender;
+package org.incendo.cloud.paper.util.sender;
 
 import io.papermc.paper.command.brigadier.CommandSourceStack;
 import org.bukkit.entity.Entity;
 import org.checkerframework.checker.nullness.qual.NonNull;
 
+/**
+ * Specialized variant of {@link Source}, for when the {@link CommandSourceStack#getSender() sender} is
+ * an {@link Entity}.
+ */
 @SuppressWarnings("UnstableApiUsage")
-public final class EntitySource extends GenericSource {
+public class EntitySource extends GenericSource {
 
     EntitySource(final CommandSourceStack commandSourceStack) {
         super(commandSourceStack);
     }
 
+    /**
+     * {@inheritDoc}
+     *
+     * @return the source
+     */
     @Override
     public @NonNull Entity source() {
         return (Entity) super.source();

cloud-paper/src/main/java/org/incendo/cloud/paper/sender/GenericSource.java → cloud-paper/src/main/java/org/incendo/cloud/paper/util/sender/GenericSource.java

@@ -21,16 +21,14 @@
 // OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
 // SOFTWARE.
 //
-package org.incendo.cloud.paper.sender;
+package org.incendo.cloud.paper.util.sender;
 
 import io.papermc.paper.command.brigadier.CommandSourceStack;
-import net.kyori.adventure.audience.Audience;
 import org.bukkit.command.CommandSender;
-import org.bukkit.entity.Entity;
 import org.checkerframework.checker.nullness.qual.NonNull;
 
 @SuppressWarnings("UnstableApiUsage")
-public class GenericSource implements Source {
+class GenericSource implements Source {
 
     private final CommandSourceStack commandSourceStack;
 
@@ -44,16 +42,12 @@ public class GenericSource implements Source {
     }
 
     /**
-     * @see Source#source()
+     * {@inheritDoc}
+     *
+     * @return the source
      */
     @Override
     public @NonNull CommandSender source() {
         return this.commandSourceStack.getSender();
     }
-
-    @Override
-    public final @NonNull Audience audience() {
-        Entity executor = this.commandSourceStack.getExecutor();
-        return executor == null ? this.commandSourceStack.getSender() : executor;
-    }
 }

cloud-paper/src/main/java/org/incendo/cloud/paper/sender/PaperSimpleSenderMapper.java → cloud-paper/src/main/java/org/incendo/cloud/paper/util/sender/PaperSimpleSenderMapper.java

@@ -21,16 +21,28 @@
 // OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
 // SOFTWARE.
 //
-package org.incendo.cloud.paper.sender;
+package org.incendo.cloud.paper.util.sender;
 
 import io.papermc.paper.command.brigadier.CommandSourceStack;
 import org.bukkit.command.CommandSender;
 import org.bukkit.command.ConsoleCommandSender;
 import org.bukkit.entity.Entity;
 import org.bukkit.entity.Player;
 import org.checkerframework.checker.nullness.qual.NonNull;
+import org.incendo.cloud.Command;
 import org.incendo.cloud.SenderMapper;
+import org.incendo.cloud.paper.PaperCommandManager;
 
+/**
+ * A simple {@link SenderMapper} implementation designed for use with {@link PaperCommandManager}.
+ * Allows for easily utilizing cloud's {@link Command.Builder#senderType(Class)} utilities despite the
+ * single {@link CommandSourceStack} implementation provided by Paper/Minecraft.
+ *
+ * <p>The {@link #map(CommandSourceStack)} implementation performs type dispatch based on the {@link CommandSourceStack#getSender() sender},
+ * for example it will create a {@link PlayerSource} when {@link CommandSourceStack#getSender()} is a {@link Player}, and similar for
+ * {@link ConsoleSource} and {@link EntitySource}. Any other specific sender types do not currently have special handling
+ * and will fall back to a generic {@link Source} implementation.</p>
+ */
 @SuppressWarnings("UnstableApiUsage")
 public final class PaperSimpleSenderMapper implements SenderMapper<CommandSourceStack, Source> {
 

cloud-paper/src/main/java/org/incendo/cloud/paper/sender/PlayerSource.java → cloud-paper/src/main/java/org/incendo/cloud/paper/util/sender/PlayerSource.java

@@ -21,14 +21,18 @@
 // OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
 // SOFTWARE.
 //
-package org.incendo.cloud.paper.sender;
+package org.incendo.cloud.paper.util.sender;
 
 import io.papermc.paper.command.brigadier.CommandSourceStack;
 import org.bukkit.entity.Player;
 import org.checkerframework.checker.nullness.qual.NonNull;
 
+/**
+ * Specialized variant of {@link Source}, for when the {@link CommandSourceStack#getSender() sender} is a
+ * {@link Player}.
+ */
 @SuppressWarnings("UnstableApiUsage")
-public final class PlayerSource extends GenericSource {
+public final class PlayerSource extends EntitySource {
 
     PlayerSource(final CommandSourceStack commandSourceStack) {
         super(commandSourceStack);

cloud-paper/src/main/java/org/incendo/cloud/paper/sender/Source.java → cloud-paper/src/main/java/org/incendo/cloud/paper/util/sender/Source.java

@@ -21,34 +21,33 @@
 // OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
 // SOFTWARE.
 //
-package org.incendo.cloud.paper.sender;
+package org.incendo.cloud.paper.util.sender;
 
 import io.papermc.paper.command.brigadier.CommandSourceStack;
-import net.kyori.adventure.audience.Audience;
 import org.bukkit.command.CommandSender;
 import org.checkerframework.checker.nullness.qual.NonNull;
 
+/**
+ * A simple wrapper around {@link CommandSourceStack}.
+ *
+ * @see PaperSimpleSenderMapper
+ */
 @SuppressWarnings("UnstableApiUsage")
 public interface Source {
 
     /**
-     * Gets the command source stack.
+     * Gets the {@link CommandSourceStack}.
      *
      * @return the command source stack
      */
     @NonNull CommandSourceStack stack();
 
     /**
-     * Gets the underlying command sender from the command source stack.
+     * Gets the underlying {@link CommandSourceStack#getSender() sender} from the {@link #stack() source stack}.
      *
-     * @return the sender.
-     */
-    @NonNull CommandSender source();
-
-    /**
-     * Gets the audience of the source.
+     * <p>Specific implementations may override this method with a more specific return type.</p>
      *
-     * @return the audience
+     * @return the source
      */
-    @NonNull Audience audience();
+    @NonNull CommandSender source();
 }

cloud-paper/src/main/java/org/incendo/cloud/paper/util/sender/package-info.java

@@ -0,0 +1,5 @@
+/**
+ * Built in command sender {@link org.incendo.cloud.paper.util.sender.Source types} and
+ * {@link org.incendo.cloud.paper.util.sender.PaperSimpleSenderMapper mappings} for modern Paper.
+ */
+package org.incendo.cloud.paper.util.sender;

examples/example-paper/src/main/java/org/incendo/cloud/examples/paper/PaperPlugin.java

@@ -27,7 +27,7 @@
 import org.checkerframework.checker.nullness.qual.NonNull;
 import org.checkerframework.framework.qual.DefaultQualifier;
 import org.incendo.cloud.paper.PaperCommandManager;
-import org.incendo.cloud.paper.sender.Source;
+import org.incendo.cloud.paper.util.sender.Source;
 
 @DefaultQualifier(NonNull.class)
 public final class PaperPlugin extends JavaPlugin {

examples/example-paper/src/main/java/org/incendo/cloud/examples/paper/PluginBootstrap.java

@@ -33,10 +33,10 @@
 import org.checkerframework.framework.qual.DefaultQualifier;
 import org.incendo.cloud.execution.ExecutionCoordinator;
 import org.incendo.cloud.paper.PaperCommandManager;
-import org.incendo.cloud.paper.sender.ConsoleSource;
-import org.incendo.cloud.paper.sender.PaperSimpleSenderMapper;
-import org.incendo.cloud.paper.sender.PlayerSource;
-import org.incendo.cloud.paper.sender.Source;
+import org.incendo.cloud.paper.util.sender.ConsoleSource;
+import org.incendo.cloud.paper.util.sender.PaperSimpleSenderMapper;
+import org.incendo.cloud.paper.util.sender.PlayerSource;
+import org.incendo.cloud.paper.util.sender.Source;
 import org.incendo.cloud.setting.ManagerSetting;
 
 import static org.incendo.cloud.parser.standard.StringParser.stringParser;