feat: better javadoc

Author: Traqueur-dev

src/main/java/fr/traqueur/jdafluent/Choice.java

@@ -29,51 +29,136 @@ public String fullLabel() {
         return emoji != null ? emoji + " " + label : label;
     }
 
+    /**
+     * Create a primary choice with just a label.
+     *
+     * @param <T> the type of value
+     * @param label the display label
+     * @param value the associated value
+     * @return a new primary choice
+     */
     @NotNull
     public static <T> Choice<T> of(@NotNull String label, @NotNull T value) {
         return new Choice<>(ButtonStyle.PRIMARY, null, label, value);
     }
 
+    /**
+     * Create a primary choice with emoji and label.
+     *
+     * @param <T> the type of value
+     * @param emoji the emoji to display
+     * @param label the display label
+     * @param value the associated value
+     * @return a new primary choice with emoji
+     */
     @NotNull
     public static <T> Choice<T> of(@NotNull String emoji, @NotNull String label, @NotNull T value) {
         return new Choice<>(ButtonStyle.PRIMARY, emoji, label, value);
     }
 
+    /**
+     * Create a primary style choice.
+     *
+     * @param <T> the type of value
+     * @param label the display label
+     * @param value the associated value
+     * @return a new primary choice
+     */
     @NotNull
     public static <T> Choice<T> primary(@NotNull String label, @NotNull T value) {
         return new Choice<>(ButtonStyle.PRIMARY, null, label, value);
     }
 
+    /**
+     * Create a primary style choice with emoji.
+     *
+     * @param <T> the type of value
+     * @param emoji the emoji to display
+     * @param label the display label
+     * @param value the associated value
+     * @return a new primary choice with emoji
+     */
     @NotNull
     public static <T> Choice<T> primary(@NotNull String emoji, @NotNull String label, @NotNull T value) {
         return new Choice<>(ButtonStyle.PRIMARY, emoji, label, value);
     }
 
+    /**
+     * Create a secondary style choice.
+     *
+     * @param <T> the type of value
+     * @param label the display label
+     * @param value the associated value
+     * @return a new secondary choice
+     */
     @NotNull
     public static <T> Choice<T> secondary(@NotNull String label, @NotNull T value) {
         return new Choice<>(ButtonStyle.SECONDARY, null, label, value);
     }
 
+    /**
+     * Create a secondary style choice with emoji.
+     *
+     * @param <T> the type of value
+     * @param emoji the emoji to display
+     * @param label the display label
+     * @param value the associated value
+     * @return a new secondary choice with emoji
+     */
     @NotNull
     public static <T> Choice<T> secondary(@NotNull String emoji, @NotNull String label, @NotNull T value) {
         return new Choice<>(ButtonStyle.SECONDARY, emoji, label, value);
     }
 
+    /**
+     * Create a success style choice.
+     *
+     * @param <T> the type of value
+     * @param label the display label
+     * @param value the associated value
+     * @return a new success choice
+     */
     @NotNull
     public static <T> Choice<T> success(@NotNull String label, @NotNull T value) {
         return new Choice<>(ButtonStyle.SUCCESS, null, label, value);
     }
 
+    /**
+     * Create a success style choice with emoji.
+     *
+     * @param <T> the type of value
+     * @param emoji the emoji to display
+     * @param label the display label
+     * @param value the associated value
+     * @return a new success choice with emoji
+     */
     @NotNull
     public static <T> Choice<T> success(@NotNull String emoji, @NotNull String label, @NotNull T value) {
         return new Choice<>(ButtonStyle.SUCCESS, emoji, label, value);
     }
 
+    /**
+     * Create a danger style choice.
+     *
+     * @param <T> the type of value
+     * @param label the display label
+     * @param value the associated value
+     * @return a new danger choice
+     */
     @NotNull
     public static <T> Choice<T> danger(@NotNull String label, @NotNull T value) {
         return new Choice<>(ButtonStyle.DANGER, null, label, value);
     }
 
+    /**
+     * Create a danger style choice with emoji.
+     *
+     * @param <T> the type of value
+     * @param emoji the emoji to display
+     * @param label the display label
+     * @param value the associated value
+     * @return a new danger choice with emoji
+     */
     @NotNull
     public static <T> Choice<T> danger(@NotNull String emoji, @NotNull String label, @NotNull T value) {
         return new Choice<>(ButtonStyle.DANGER, emoji, label, value);

src/main/java/fr/traqueur/jdafluent/JDAFluent.java

@@ -66,6 +66,11 @@ public class JDAFluent {
     private final Selects selects;
     private final Awaiters awaiters;
 
+    /**
+     * Create a new JDAFluent instance.
+     *
+     * @param jda the JDA instance to use
+     */
     public JDAFluent(@NotNull JDA jda) {
         this.jda = jda;
         this.buttons = new Buttons();
@@ -81,6 +86,8 @@ public JDAFluent(@NotNull JDA jda) {
 
     /**
      * Get the JDA instance.
+     *
+     * @return the JDA instance
      */
     @NotNull
     public JDA jda() {
@@ -89,6 +96,8 @@ public JDA jda() {
 
     /**
      * Get the buttons registry for low-level button management.
+     *
+     * @return the Buttons instance
      */
     @NotNull
     public Buttons buttons() {
@@ -97,6 +106,8 @@ public Buttons buttons() {
 
     /**
      * Get the dialogs factory for ephemeral interactions.
+     *
+     * @return the Dialogs instance
      */
     @NotNull
     public Dialogs dialogs() {
@@ -105,6 +116,8 @@ public Dialogs dialogs() {
 
     /**
      * Get the panels factory for permanent interactions.
+     *
+     * @return the Panels instance
      */
     @NotNull
     public Panels panels() {
@@ -113,6 +126,8 @@ public Panels panels() {
 
     /**
      * Get the modals factory for modal dialogs.
+     *
+     * @return the Modals instance
      */
     @NotNull
     public Modals modals() {
@@ -121,6 +136,8 @@ public Modals modals() {
 
     /**
      * Get the selects factory for select menus.
+     *
+     * @return the Selects instance
      */
     @NotNull
     public Selects selects() {
@@ -129,6 +146,8 @@ public Selects selects() {
 
     /**
      * Get the awaiters factory for waiting on events.
+     *
+     * @return the Awaiters instance
      */
     @NotNull
     public Awaiters awaiters() {
@@ -137,6 +156,8 @@ public Awaiters awaiters() {
 
     /**
      * Get a combined listener for all interactions.
+     *
+     * @return a ListenerAdapter that handles all interaction events
      */
     @NotNull
     public ListenerAdapter asListener() {

src/main/java/fr/traqueur/jdafluent/awaiters/Awaiter.java

@@ -22,21 +22,55 @@
  */
 public abstract class Awaiter<E extends GenericEvent, R, S extends Awaiter<E, R, S>> {
 
+    /**
+     * The awaiters factory containing JDA and scheduler.
+     */
     protected final Awaiters awaiters;
 
+    /**
+     * The user to filter events from, or null for any user.
+     */
     protected User fromUser;
+
+    /**
+     * The channel to filter events in, or null for any channel.
+     */
     protected MessageChannel inChannel;
+
+    /**
+     * The timeout duration before the awaiter expires.
+     */
     protected Duration timeout = Duration.ofMinutes(1);
+
+    /**
+     * Additional filter predicate for results.
+     */
     protected Predicate<R> filter = r -> true;
+
+    /**
+     * Handler called when a matching event is received.
+     */
     protected Consumer<R> onResponse;
+
+    /**
+     * Handler called when the timeout is reached.
+     */
     protected Runnable onTimeout;
 
+    /**
+     * Creates a new awaiter.
+     *
+     * @param awaiters the awaiters factory
+     */
     protected Awaiter(@NotNull Awaiters awaiters) {
         this.awaiters = awaiters;
     }
 
     /**
      * Only accept events from this user.
+     *
+     * @param user the user to filter events from
+     * @return this awaiter for chaining
      */
     @NotNull
     public S from(@NotNull User user) {
@@ -46,6 +80,9 @@ public S from(@NotNull User user) {
 
     /**
      * Only accept events in this channel.
+     *
+     * @param channel the channel to filter events in
+     * @return this awaiter for chaining
      */
     @NotNull
     public S inChannel(@NotNull MessageChannel channel) {
@@ -55,6 +92,9 @@ public S inChannel(@NotNull MessageChannel channel) {
 
     /**
      * Set the timeout duration.
+     *
+     * @param timeout the timeout duration
+     * @return this awaiter for chaining
      */
     @NotNull
     public S timeout(@NotNull Duration timeout) {
@@ -64,6 +104,9 @@ public S timeout(@NotNull Duration timeout) {
 
     /**
      * Additional filter for results.
+     *
+     * @param filter the filter predicate to apply
+     * @return this awaiter for chaining
      */
     @NotNull
     public S filter(@NotNull Predicate<R> filter) {
@@ -73,6 +116,9 @@ public S filter(@NotNull Predicate<R> filter) {
 
     /**
      * Handler when a matching event is received.
+     *
+     * @param handler the handler to call with the result
+     * @return this awaiter for chaining
      */
     @NotNull
     public S onResponse(@NotNull Consumer<R> handler) {
@@ -82,6 +128,9 @@ public S onResponse(@NotNull Consumer<R> handler) {
 
     /**
      * Handler when timeout is reached.
+     *
+     * @param handler the handler to call on timeout
+     * @return this awaiter for chaining
      */
     @NotNull
     public S onTimeout(@NotNull Runnable handler) {
@@ -113,36 +162,52 @@ public void start() {
 
     /**
      * Return this as the self type for fluent chaining.
+     *
+     * @return this awaiter cast to the self type
      */
     @NotNull
     protected abstract S self();
 
     /**
      * Get the event class to listen for.
+     *
+     * @return the event class
      */
     @NotNull
     protected abstract Class<E> getEventClass();
 
     /**
      * Extract the user from the event (for filtering).
+     *
+     * @param event the event to extract from
+     * @return the user, or null if not applicable
      */
     @Nullable
     protected abstract User extractUser(@NotNull E event);
 
     /**
      * Extract the channel from the event (for filtering).
+     *
+     * @param event the event to extract from
+     * @return the channel, or null if not applicable
      */
     @Nullable
     protected abstract MessageChannel extractChannel(@NotNull E event);
 
     /**
      * Extract the result from the event.
+     *
+     * @param event the event to extract from
+     * @return the extracted result
      */
     @NotNull
     protected abstract R extractResult(@NotNull E event);
 
     /**
      * Check if the event should be ignored (e.g., bot messages).
+     *
+     * @param event the event to check
+     * @return true if the event should be ignored
      */
     protected boolean shouldIgnore(@NotNull E event) {
         return false;
@@ -151,6 +216,8 @@ protected boolean shouldIgnore(@NotNull E event) {
     /**
      * Called after a successful match, before the handler.
      * Can be used for cleanup like deleting messages.
+     *
+     * @param event the matched event
      */
     protected void onMatch(@NotNull E event) {
         // Default: do nothing