Add javadocs for main facade codebase (#26)

honey-common/src/dev/shiza/honey/adventure/message/compiler/AdventureMessageCompiler.java

@@ -13,21 +13,39 @@
 import net.kyori.adventure.text.minimessage.tag.resolver.TagResolver;
 import org.intellij.lang.annotations.Subst;
 
+/**
+* This class provides a mechanism to compile messages using the Adventure API MiniMessage format.
+* It translates sanitized content and placeholders into formatted Adventure {@link Component}s.
+*/
 final class AdventureMessageCompiler implements MessageCompiler<Component> {
 
+
   private final MiniMessage miniMessage;
 
   AdventureMessageCompiler(final MiniMessage miniMessage) {
     this.miniMessage = miniMessage;
   }
 
+  /**
+  * Compiles the sanitized content and placeholders into an Adventure {@link Component}.
+  *
+  * @param sanitizedContent The sanitized content string to be compiled.
+  * @param placeholders The list of sanitized placeholders to be included in the content.
+  * @return The compiled message as an Adventure {@link Component}.
+  */
   @Override
   public Component compile(
       final String sanitizedContent, final List<SanitizedPlaceholder> placeholders) {
     final TagResolver[] placeholderTags = getPlaceholderTags(placeholders);
     return miniMessage.deserialize(sanitizedContent, placeholderTags);
   }
 
+  /**
+  * Converts a list of {@link SanitizedPlaceholder} into an array of {@link TagResolver}.
+  *
+  * @param placeholders The list of placeholders to be converted.
+  * @return An array of {@link TagResolver}.
+  */
   private TagResolver[] getPlaceholderTags(final List<SanitizedPlaceholder> placeholders) {
     final TagResolver[] tagResolvers = new TagResolver[placeholders.size()];
     for (int index = 0; index < tagResolvers.length; index++) {
@@ -37,6 +55,14 @@ private TagResolver[] getPlaceholderTags(final List<SanitizedPlaceholder> placeh
     return tagResolvers;
   }
 
+  /**
+  * Creates a {@link TagResolver} based on the key and the evaluated value of the placeholder.
+  * The method handles different types of evaluated values by converting them into suitable tag resolutions.
+  *
+  * @param key The key associated with the placeholder.
+  * @param evaluatedValue The evaluated value of the placeholder.
+  * @return The appropriate {@link TagResolver} based on the type of evaluated value.
+  */
   private TagResolver getPlaceholderTags(
       final @Subst("default") String key, final Object evaluatedValue) {
     if (evaluatedValue instanceof Component component) {

honey-common/src/dev/shiza/honey/adventure/message/compiler/AdventureMessageCompilerFactory.java

@@ -6,14 +6,29 @@
 import net.kyori.adventure.text.Component;
 import net.kyori.adventure.text.minimessage.MiniMessage;
 
+/**
+* Factory for creating Adventure message compilers.
+*/
 public final class AdventureMessageCompilerFactory {
 
-  private AdventureMessageCompilerFactory() {}
+  private AdventureMessageCompilerFactory() {
+  }
 
+  /**
+  * Creates a message compiler using a specific MiniMessage.
+  *
+  * @param miniMessage the MiniMessage instance to use for the compiler.
+  * @return a new instance of {@link MessageCompiler<Component>} configured with the given MiniMessage.
+  */
   public static MessageCompiler<Component> create(final MiniMessage miniMessage) {
     return new AdventureMessageCompiler(miniMessage);
   }
 
+  /**
+  * Creates a default message compiler with default MiniMessage configuration.
+  *
+  * @return a new instance of {@link MessageCompiler<Component>} with the default MiniMessage configuration.
+  */
   public static MessageCompiler<Component> create() {
     return new AdventureMessageCompiler(miniMessage());
   }

honey-common/src/dev/shiza/honey/adventure/message/dispatcher/AdventureMessageDispatcher.java

@@ -6,19 +6,40 @@
 import net.kyori.adventure.audience.Audience;
 import net.kyori.adventure.text.Component;
 
+/**
+* AdventureMessageDispatcher provides static factory methods to create various types of message dispatchers
+* for use in an adventure game context. This class cannot be instantiated and provides centralized
+* access to functions creating dispatchers for chat messages, action bars, and titles.
+*/
 public final class AdventureMessageDispatcher {
 
-  private AdventureMessageDispatcher() {}
+  private AdventureMessageDispatcher() {
+  }
 
+  /**
+  * Creates a MessageDispatcher for sending chat messages.
+  *
+  * @return A MessageDispatcher instance configured to send chat messages to an Audience.
+  */
   public static MessageDispatcher<Audience, Component> createChat() {
     return new MessageBaseDispatcher<>(Audience.empty(), Audience::sendMessage);
   }
 
+  /**
+  * Creates a MessageDispatcher for sending action bar messages.
+  *
+  * @return A MessageDispatcher instance configured to send action bar messages to an Audience.
+  */
   public static MessageDispatcher<Audience, Component> createActionBar() {
     return new MessageBaseDispatcher<>(Audience.empty(), Audience::sendActionBar);
   }
 
+  /**
+  * Creates a TitleMessageDispatcher for sending title messages.
+  *
+  * @return A TitleMessageDispatcher instance configured to send title messages to an Audience.
+  */
   public static TitleMessageDispatcher<Audience, Component> createTitle() {
     return new AdventureTitleMessageDispatcher();
   }
-}
+}

honey-common/src/dev/shiza/honey/adventure/message/dispatcher/AdventureTitleMessageDispatcher.java

@@ -15,82 +15,136 @@
 import net.kyori.adventure.title.Title.Times;
 import net.kyori.adventure.title.TitlePart;
 
+/**
+* This class is responsible for dispatching title messages to an audience in the Adventure framework.
+* It manages separate dispatchers for times, title, and subtitle, as well as keeping track of the recipient.
+*
+* @param IN <Audience> the audience type that the messages are dispatched to
+* @param OUT <Component> the message component type
+*/
 public final class AdventureTitleMessageDispatcher
     implements TitleMessageDispatcher<Audience, Component> {
 
-  private final MessageDispatcher<Audience, Component> times;
-  private final MessageDispatcher<Audience, Component> title;
-  private final MessageDispatcher<Audience, Component> subtitle;
-  private final Audience recipient;
+    private final MessageDispatcher<Audience, Component> times;
+    private final MessageDispatcher<Audience, Component> title;
+    private final MessageDispatcher<Audience, Component> subtitle;
+    private final Audience recipient;
 
-  public AdventureTitleMessageDispatcher(
-      final MessageDispatcher<Audience, Component> times,
-      final MessageDispatcher<Audience, Component> title,
-      final MessageDispatcher<Audience, Component> subtitle,
-      final Audience recipient) {
-    this.times = times;
-    this.title = title;
-    this.subtitle = subtitle;
-    this.recipient = recipient;
-  }
+    /**
+    * Constructs a new AdventureTitleMessageDispatcher with specified dispatchers for times, title, subtitle and a recipient.
+    *
+    * @param times the dispatcher for handling the timing of title messages
+    * @param title the dispatcher for handling the main title messages
+    * @param subtitle the dispatcher for handling the subtitle messages
+    * @param recipient the audience that will receive the title messages
+    */
+    public AdventureTitleMessageDispatcher(
+        final MessageDispatcher<Audience, Component> times,
+        final MessageDispatcher<Audience, Component> title,
+        final MessageDispatcher<Audience, Component> subtitle,
+        final Audience recipient) {
+        this.times = times;
+        this.title = title;
+        this.subtitle = subtitle;
+        this.recipient = recipient;
+    }
 
-  public AdventureTitleMessageDispatcher() {
-    this(
-        new MessageBaseDispatcher<>(
-            Audience.empty(),
-            (audience, component) -> audience.sendTitlePart(TitlePart.TIMES, Title.DEFAULT_TIMES)),
-        new MessageBaseDispatcher<>(
-            Audience.empty(),
-            (audience, component) -> audience.sendTitlePart(TitlePart.TITLE, component)),
-        new MessageBaseDispatcher<>(
-            Audience.empty(),
-            (audience, component) -> audience.sendTitlePart(TitlePart.SUBTITLE, component)),
-        Audience.empty());
-  }
+    /**
+    * Default constructor that initializes with default dispatchers for times, title, and subtitle,
+    * with an empty recipient.
+    */
+    public AdventureTitleMessageDispatcher() {
+        this(
+            new MessageBaseDispatcher<>(
+                Audience.empty(),
+                (audience, component) -> audience.sendTitlePart(TitlePart.TIMES, Title.DEFAULT_TIMES)),
+            new MessageBaseDispatcher<>(
+                Audience.empty(),
+                (audience, component) -> audience.sendTitlePart(TitlePart.TITLE, component)),
+            new MessageBaseDispatcher<>(
+                Audience.empty(),
+                (audience, component) -> audience.sendTitlePart(TitlePart.SUBTITLE, component)),
+            Audience.empty());
+    }
 
-  @Override
-  public TitleMessageDispatcher<Audience, Component> times(
-      final int fadeIn, final int stay, final int fadeOut) {
-    final Times titleTime =
-        Times.times(
-            Duration.ofSeconds(fadeIn), Duration.ofSeconds(stay), Duration.ofSeconds(fadeOut));
-    final MessageDispatcher<Audience, Component> timesDispatcher =
-        new MessageBaseDispatcher<>(
+    /**
+    * Sets the times for the title message.
+    *
+    * @param fadeIn duration in seconds for title fade-in
+    * @param stay duration in seconds the title should stay visible
+    * @param fadeOut duration in seconds for title fade-out
+    * @return a new instance of AdventureTitleMessageDispatcher with updated times dispatcher
+    */
+    @Override
+    public TitleMessageDispatcher<Audience, Component> times(
+        final int fadeIn, final int stay, final int fadeOut) {
+        final Times titleTime =
+            Times.times(
+                Duration.ofSeconds(fadeIn), Duration.ofSeconds(stay), Duration.ofSeconds(fadeOut));
+        final MessageDispatcher<Audience, Component> timesDispatcher =
+            new MessageBaseDispatcher<>(
             recipient, (audience, component) -> audience.sendTitlePart(TitlePart.TIMES, titleTime));
-    return new AdventureTitleMessageDispatcher(
-        timesDispatcher.template(Component.empty()), title, subtitle, recipient);
-  }
+        return new AdventureTitleMessageDispatcher(
+                   timesDispatcher.template(Component.empty()), title, subtitle, recipient);
+    }
 
-  @Override
-  public TitleMessageDispatcher<Audience, Component> title(
-      final UnaryOperator<MessageDispatcher<Audience, Component>> consumer) {
-    return new AdventureTitleMessageDispatcher(times, consumer.apply(title), subtitle, recipient);
-  }
+    /**
+    * Modifies the title dispatcher.
+    *
+    * @param consumer the function to modify the title dispatcher
+    * @return a new instance of AdventureTitleMessageDispatcher with updated title dispatcher
+    */
+    @Override
+    public TitleMessageDispatcher<Audience, Component> title(
+        final UnaryOperator<MessageDispatcher<Audience, Component>> consumer) {
+        return new AdventureTitleMessageDispatcher(times, consumer.apply(title), subtitle, recipient);
+    }
 
-  @Override
-  public TitleMessageDispatcher<Audience, Component> subtitle(
-      final UnaryOperator<MessageDispatcher<Audience, Component>> consumer) {
-    return new AdventureTitleMessageDispatcher(times, title, consumer.apply(subtitle), recipient);
-  }
+    /**
+    * Modifies the subtitle dispatcher.
+    *
+    * @param consumer the function to modify the subtitle dispatcher
+    * @return a new instance of AdventureTitleMessageDispatcher with updated subtitle dispatcher
+    */
+    @Override
+    public TitleMessageDispatcher<Audience, Component> subtitle(
+        final UnaryOperator<MessageDispatcher<Audience, Component>> consumer) {
+        return new AdventureTitleMessageDispatcher(times, title, consumer.apply(subtitle), recipient);
+    }
 
-  @Override
-  public TitleMessageDispatcher<Audience, Component> recipient(final Audience recipient) {
-    return new AdventureTitleMessageDispatcher(times, title, subtitle, recipient);
-  }
+    /**
+    * Updates the recipient of title messages.
+    *
+    * @param recipient the new recipient for the title messages
+    * @return a new instance of AdventureTitleMessageDispatcher with the updated recipient
+    */
+    @Override
+    public TitleMessageDispatcher<Audience, Component> recipient(final Audience recipient) {
+        return new AdventureTitleMessageDispatcher(times, title, subtitle, recipient);
+    }
 
-  @Override
-  public void dispatch() {
-    times.recipient(recipient).dispatch();
-    title.recipient(recipient).dispatch();
-    subtitle.recipient(recipient).dispatch();
-  }
+    /**
+    * Dispatches the title, subtitle, and timing messages to the recipient synchronously.
+    */
+    @Override
+    public void dispatch() {
+        times.recipient(recipient).dispatch();
+        title.recipient(recipient).dispatch();
+        subtitle.recipient(recipient).dispatch();
+    }
 
-  @Override
-  public CompletableFuture<List<Void>> dispatchAsync() {
-    return CompletableFutures.allAsList(
-        ImmutableList.of(
-            times.recipient(recipient).dispatchAsync(),
-            title.recipient(recipient).dispatchAsync(),
-            subtitle.recipient(recipient).dispatchAsync()));
-  }
+    /**
+    * Dispatches the title, subtitle, and timing messages to the recipient asynchronously.
+    *
+    * @return a CompletableFuture representing pending completion of the task,
+    * with a list of Void, indicating when all dispatches are complete
+    */
+    @Override
+    public CompletableFuture<List<Void>> dispatchAsync() {
+        return CompletableFutures.allAsList(
+                   ImmutableList.of(
+                       times.recipient(recipient).dispatchAsync(),
+                       title.recipient(recipient).dispatchAsync(),
+                       subtitle.recipient(recipient).dispatchAsync()));
+    }
 }

honey-common/src/dev/shiza/honey/adventure/message/formatter/AdventureMessageFormatter.java

@@ -9,21 +9,35 @@
 import dev.shiza.honey.processor.ProcessorRegistry;
 import net.kyori.adventure.text.Component;
 
+/**
+* Represents a specific implementation of {@link MessageBaseFormatter} for handling Adventure components.
+* This class leverages the message formatting system specifically tailored for Adventure library components.
+*/
 public final class AdventureMessageFormatter extends MessageBaseFormatter<Component> {
 
+  /**
+  * Constructs an AdventureMessageFormatter with required components for message compiling and processing.
+  *
+  * @param messageCompiler the compiler responsible for message compilation.
+  * @param placeholderContext the context for processing placeholders.
+  * @param placeholderResolver responsible for resolving placeholders.
+  * @param placeholderProcessor processor to apply transformations on placeholders.
+  * @param placeholderSanitizer sanitizer to clean or adjust placeholders according to specific rules.
+  * @param processorRegistry registry to keep track of processors and manage them.
+  */
   AdventureMessageFormatter(
-      final MessageCompiler<Component> messageCompiler,
-      final PlaceholderContext placeholderContext,
-      final PlaceholderResolver placeholderResolver,
-      final PlaceholderProcessor placeholderProcessor,
-      final PlaceholderSanitizer placeholderSanitizer,
-      final ProcessorRegistry processorRegistry) {
+    final MessageCompiler<Component> messageCompiler,
+    final PlaceholderContext placeholderContext,
+    final PlaceholderResolver placeholderResolver,
+    final PlaceholderProcessor placeholderProcessor,
+    final PlaceholderSanitizer placeholderSanitizer,
+    final ProcessorRegistry processorRegistry) {
     super(
-        messageCompiler,
-        placeholderContext,
-        placeholderResolver,
-        placeholderProcessor,
-        placeholderSanitizer,
-        processorRegistry);
+      messageCompiler,
+      placeholderContext,
+      placeholderResolver,
+      placeholderProcessor,
+      placeholderSanitizer,
+      processorRegistry);
   }
-}
+}