Add docs for RecipientsResolver

Author: jpenilla

api/src/main/java/net/draycia/carbon/api/channels/RecipientsResolver.java

@@ -28,10 +28,36 @@
 import net.kyori.adventure.key.Key;
 import org.checkerframework.common.returnsreceiver.qual.This;
 
+/**
+ * Resolves the recipients for a message from a given sender.
+ *
+ * @see ChatChannel#recipientsResolver()
+ * @see #builder(CarbonServer)
+ * @since 3.0.0
+ */
 @FunctionalInterface
 public interface RecipientsResolver {
+
+    /**
+     * Resolves the recipients for a message from a given sender.
+     *
+     * @param sender the sender to resolve recipients for
+     * @return resolved recipients
+     * @since 3.0.0
+     */
     List<Audience> recipients(CarbonPlayer sender);
 
+    /**
+     * Creates a new combined {@link RecipientsResolver} from this resolver and {@code resolver}.
+     *
+     * <p>
+     * Note that this method does not filter duplicate audiences.
+     * </p>
+     *
+     * @param resolver second resolver
+     * @return new combined resolver
+     * @since 3.0.0
+     */
     default RecipientsResolver and(final RecipientsResolver resolver) {
         return sender -> {
             final List<Audience> recipients = new ArrayList<>(this.recipients(sender));
@@ -40,10 +66,25 @@ default RecipientsResolver and(final RecipientsResolver resolver) {
         };
     }
 
+    /**
+     * Creates a new {@link Builder}.
+     *
+     * @param server server instance
+     * @return new {@link Builder}
+     * @since 3.0.0
+     */
     static Builder builder(final CarbonServer server) {
         return new Builder(server);
     }
 
+    /**
+     * Mutable builder for {@link RecipientsResolver}.
+     * <p>
+     * Custom implementations are supported, however the builder simplifies most use cases.
+     * </p>
+     *
+     * @since 3.0.0
+     */
     final class Builder {
         private final CarbonServer server;
         private final List<Predicate<CarbonPlayer>> playerFilters = new ArrayList<>();
@@ -53,26 +94,62 @@ private Builder(final CarbonServer server) {
             this.server = server;
         }
 
+        /**
+         * Includes online players with permission to hear the channel that have not left the channel,
+         * using {@link #players(Predicate)}.
+         *
+         * @param channel channel
+         * @return this builder
+         * @since 3.0.0
+         */
         public @This Builder permittedPlayersInChannel(final ChatChannel channel) {
             return this.permittedPlayersInChannel(channel.permissions(), channel.key());
         }
 
+        /**
+         * Includes online players with permission to hear the channel that have not left the channel,
+         * using {@link #players(Predicate)}.
+         *
+         * @param permissions permissions
+         * @param channelKey channel
+         * @return this builder
+         * @since 3.0.0
+         */
         public @This Builder permittedPlayersInChannel(final ChannelPermissions permissions, final Key channelKey) {
-            this.playerFilters.add(player -> permissions.hearingPermitted(player).permitted()
+            return this.players(player -> permissions.hearingPermitted(player).permitted()
                 && !player.leftChannels().contains(channelKey));
-            return this;
         }
 
+        /**
+         * Includes online players matching the predicate in the resolved recipients. Adding multiple predicates
+         * will include players matching any one of the predicate.
+         *
+         * @param filter player filter
+         * @return this builder
+         * @since 3.0.0
+         */
         public @This Builder players(final Predicate<CarbonPlayer> filter) {
             this.playerFilters.add(filter);
             return this;
         }
 
+        /**
+         * Unconditionally includes the console in the resolved recipients.
+         *
+         * @return this builder
+         * @since 3.0.0
+         */
         public @This Builder console() {
             this.includeConsole = true;
             return this;
         }
 
+        /**
+         * Builds a new {@link RecipientsResolver} from the current state of this builder.
+         *
+         * @return new {@link RecipientsResolver} instance
+         * @since 3.0.0
+         */
         public RecipientsResolver build() {
             final boolean includeConsole = this.includeConsole;
             final List<Predicate<CarbonPlayer>> playerFilters = List.copyOf(this.playerFilters);