javadoc and some readability changes

Author: Zabuzard

application/src/main/java/org/togetherjava/tjbot/features/tophelper/TopHelpersAssignmentRoutine.java

@@ -6,6 +6,7 @@
 import net.dv8tion.jda.api.entities.Role;
 import net.dv8tion.jda.api.entities.UserSnowflake;
 import net.dv8tion.jda.api.entities.channel.concrete.TextChannel;
+import net.dv8tion.jda.api.entities.channel.middleman.MessageChannel;
 import net.dv8tion.jda.api.events.interaction.component.ButtonInteractionEvent;
 import net.dv8tion.jda.api.events.interaction.component.StringSelectInteractionEvent;
 import net.dv8tion.jda.api.interactions.components.ComponentInteraction;
@@ -43,7 +44,18 @@
 import java.util.stream.Collectors;
 import java.util.stream.Stream;
 
-// TODO Javadoc everywhere
+/**
+ * Semi-automatic routine for assigning and announcing Top Helpers of the month.
+ * <p>
+ * The routine triggers once on the 1st of each month, but can also be started manually by calling
+ * {@link #startDialogFor(Guild)}.
+ * <p>
+ * The routine starts a dialog in a configured channel, proposing a list of Top Helpers. A user can
+ * now choose from a list who to reward with the Top Helper role. These users are now assigned the
+ * configured Top Helper role, while users who had the role in the past have it removed from them.
+ * Afterward, one can select from the dialog whether a generic announcement that thanks the selected
+ * Top Helpers should be posted in a configured channel.
+ */
 public final class TopHelpersAssignmentRoutine implements Routine, UserInteractor {
     private static final Logger logger = LoggerFactory.getLogger(TopHelpersAssignmentRoutine.class);
     private static final int CHECK_AT_HOUR = 12;
@@ -58,6 +70,12 @@ public final class TopHelpersAssignmentRoutine implements Routine, UserInteracto
     private final Predicate<String> announcementChannelNamePredicate;
     private final ComponentIdInteractor componentIdInteractor;
 
+    /**
+     * Creates a new instance.
+     * 
+     * @param config the config to use
+     * @param service the service to use to compute Top Helpers
+     */
     public TopHelpersAssignmentRoutine(Config config, TopHelpersService service) {
         this.config = config.getTopHelpers();
         this.service = service;
@@ -88,19 +106,30 @@ public void acceptComponentIdGenerator(ComponentIdGenerator generator) {
 
     @Override
     public Schedule createSchedule() {
+        // Routine schedules are hour-based. Ensuring it only triggers once per a month is done
+        // inside the routine as early-check instead.
         return Schedule.atFixedHour(CHECK_AT_HOUR);
     }
 
     @Override
     public void runRoutine(JDA jda) {
-        int dayOfMonth = Instant.now().atOffset(ZoneOffset.UTC).getDayOfMonth();
-        if (dayOfMonth != 1) {
+        if (!isFirstDayOfMonth()) {
             return;
         }
 
         jda.getGuilds().forEach(this::startDialogFor);
     }
 
+    private static boolean isFirstDayOfMonth() {
+        return Instant.now().atOffset(ZoneOffset.UTC).getDayOfMonth() == 1;
+    }
+
+    /**
+     * Starts a dialog for semi-automatic Top Helper assignment and announcement. See
+     * {@link TopHelpersAssignmentRoutine} for details.
+     *
+     * @param guild to start the dialog and compute Top Helpers for
+     */
     public void startDialogFor(Guild guild) {
         Optional<TextChannel> assignmentChannel = guild.getTextChannelCache()
             .stream()
@@ -116,8 +145,8 @@ private void startDialogIn(TextChannel channel) {
         Guild guild = channel.getGuild();
 
         TopHelpersService.TimeRange timeRange = TopHelpersService.TimeRange.ofPreviousMonth();
-        List<TopHelpersService.TopHelperResult> topHelpers = service
-            .computeTopHelpersDescending(guild.getIdLong(), timeRange.start(), timeRange.end());
+        List<TopHelpersService.TopHelperStats> topHelpers =
+                service.computeTopHelpersDescending(guild, timeRange);
 
         if (topHelpers.isEmpty()) {
             channel.sendMessage(
@@ -127,24 +156,21 @@ private void startDialogIn(TextChannel channel) {
             return;
         }
 
-        service.retrieveTopHelperMembers(topHelpers, guild)
-            .onSuccess(members -> sendSelectionMenu(topHelpers, members, timeRange, channel))
-            .onError(error -> {
-                logger.warn("Failed to compute top-helpers for automatic assignment", error);
-                channel.sendMessage("Wanted to assign Top Helpers, but something went wrong.")
-                    .queue();
-            });
+        TopHelpersService.retrieveTopHelperMembers(topHelpers, guild).onError(error -> {
+            logger.warn("Failed to compute top-helpers for automatic assignment", error);
+            channel.sendMessage("Wanted to assign Top Helpers, but something went wrong.").queue();
+        }).onSuccess(members -> sendSelectionMenu(topHelpers, members, timeRange, channel));
     }
 
-    private void sendSelectionMenu(Collection<TopHelpersService.TopHelperResult> topHelpers,
+    private void sendSelectionMenu(Collection<TopHelpersService.TopHelperStats> topHelpers,
             Collection<? extends Member> members, TopHelpersService.TimeRange timeRange,
-            TextChannel channel) {
+            MessageChannel channel) {
         String content = """
                 Starting assignment of Top Helpers for %s:
                 ```java
                 %s
                 ```""".formatted(timeRange.description(),
-                service.asAsciiTable(topHelpers, members, false));
+                TopHelpersService.asAsciiTable(topHelpers, members));
 
         StringSelectMenu.Builder menu =
                 StringSelectMenu.create(componentIdInteractor.generateComponentId())
@@ -168,7 +194,7 @@ private void sendSelectionMenu(Collection<TopHelpersService.TopHelperResult> top
         channel.sendMessage(message).queue();
     }
 
-    private static SelectOption topHelperToSelectOption(TopHelpersService.TopHelperResult topHelper,
+    private static SelectOption topHelperToSelectOption(TopHelpersService.TopHelperStats topHelper,
             @Nullable Member member) {
         String id = Long.toString(topHelper.authorId());
 
@@ -179,19 +205,6 @@ private static SelectOption topHelperToSelectOption(TopHelpersService.TopHelperR
         return SelectOption.of(label, id);
     }
 
-    @Override
-    public void onButtonClick(ButtonInteractionEvent event, List<String> args) {
-        event.deferEdit().queue();
-        String name = args.getFirst();
-
-        switch (name) {
-            case CANCEL_BUTTON_NAME -> endFlow(event, "cancelled");
-            case NO_MESSAGE_BUTTON_NAME -> endFlow(event, "not posting an announcement");
-            case YES_MESSAGE_BUTTON_NAME -> prepareAnnouncement(event, args);
-            default -> throw new AssertionError("Unknown button name: " + name);
-        }
-    }
-
     @Override
     public void onStringSelectSelection(StringSelectInteractionEvent event, List<String> args) {
         Guild guild = Objects.requireNonNull(event.getGuild());
@@ -214,17 +227,16 @@ public void onStringSelectSelection(StringSelectInteractionEvent event, List<Str
         }
 
         event.deferEdit().queue();
-        guild.findMembersWithRoles(List.of(topHelperRole.orElseThrow()))
+        guild.findMembersWithRoles(List.of(topHelperRole.orElseThrow())).onError(error -> {
+            logger.warn("Failed to find existing top-helpers for automatic assignment", error);
+            event.getHook()
+                .editOriginal(event.getMessage()
+                        + "\n❌ Sorry, something went wrong trying to find existing top-helpers.")
+                .setComponents()
+                .queue();
+        })
             .onSuccess(currentTopHelpers -> manageTopHelperRole(currentTopHelpers,
-                    selectedTopHelperIds, event, topHelperRole.orElseThrow()))
-            .onError(error -> {
-                logger.warn("Failed to find existing top-helpers for automatic assignment", error);
-                event.getHook()
-                    .editOriginal(event.getMessage()
-                            + "\n❌ Sorry, something went wrong trying to find existing top-helpers.")
-                    .setComponents()
-                    .queue();
-            });
+                    selectedTopHelperIds, event, topHelperRole.orElseThrow()));
     }
 
     private void manageTopHelperRole(Collection<? extends Member> currentTopHelpers,
@@ -275,20 +287,30 @@ private void reportRoleManageSuccess(StringSelectInteractionEvent event) {
             .queue();
     }
 
+    @Override
+    public void onButtonClick(ButtonInteractionEvent event, List<String> args) {
+        event.deferEdit().queue();
+        String name = args.getFirst();
+
+        switch (name) {
+            case YES_MESSAGE_BUTTON_NAME -> prepareAnnouncement(event, args);
+            case NO_MESSAGE_BUTTON_NAME -> reportFlowFinished(event, "not posting an announcement");
+            case CANCEL_BUTTON_NAME -> reportFlowFinished(event, "cancelled");
+            default -> throw new AssertionError("Unknown button name: " + name);
+        }
+    }
+
     private void prepareAnnouncement(ButtonInteractionEvent event, List<String> args) {
         List<Long> topHelperIds = args.stream().skip(1).map(Long::parseLong).toList();
 
-        event.getGuild()
-            .retrieveMembersByIds(topHelperIds)
-            .onSuccess(topHelpers -> postAnnouncement(event, topHelpers))
-            .onError(error -> {
-                logger.warn("Failed to retrieve top-helper data for automatic assignment", error);
-                event.getHook()
-                    .editOriginal(event.getMessage()
-                            + "\n❌ Sorry, something went wrong trying to retrieve top-helper data.")
-                    .setComponents()
-                    .queue();
-            });
+        event.getGuild().retrieveMembersByIds(topHelperIds).onError(error -> {
+            logger.warn("Failed to retrieve top-helper data for automatic assignment", error);
+            event.getHook()
+                .editOriginal(event.getMessage()
+                        + "\n❌ Sorry, something went wrong trying to retrieve top-helper data.")
+                .setComponents()
+                .queue();
+        }).onSuccess(topHelpers -> postAnnouncement(event, topHelpers));
     }
 
     private void postAnnouncement(ButtonInteractionEvent event, List<? extends Member> topHelpers) {
@@ -310,7 +332,9 @@ private void postAnnouncement(ButtonInteractionEvent event, List<? extends Membe
             return;
         }
 
-        Collections.shuffle(topHelpers); // for fairness
+        // For fairness Top Helpers in the announcement are ordered randomly
+        Collections.shuffle(topHelpers);
+
         String topHelperList = topHelpers.stream()
             .map(Member::getAsMention)
             .map(mention -> "* " + mention)
@@ -321,12 +345,12 @@ private void postAnnouncement(ButtonInteractionEvent event, List<? extends Membe
 
         announcementChannel.orElseThrow().sendMessage(announcement).queue();
 
-        endFlow(event, "posted an announcement");
+        reportFlowFinished(event, "posted an announcement");
     }
 
-    private void endFlow(ComponentInteraction event, String message) {
-        String content = event.getMessage().getContentRaw() + "\n✅ Okay, " + message
-                + ". See you next time 👋";
+    private void reportFlowFinished(ComponentInteraction event, String phrase) {
+        String content = "%s%n✅ Okay, %s. See you next time 👋"
+            .formatted(event.getMessage().getContentRaw(), phrase);
         event.getHook().editOriginal(content).setComponents().queue();
     }
 }

application/src/main/java/org/togetherjava/tjbot/features/tophelper/TopHelpersCommand.java

@@ -1,5 +1,6 @@
 package org.togetherjava.tjbot.features.tophelper;
 
+import net.dv8tion.jda.api.entities.Guild;
 import net.dv8tion.jda.api.entities.Member;
 import net.dv8tion.jda.api.events.interaction.command.SlashCommandInteractionEvent;
 import net.dv8tion.jda.api.interactions.callbacks.IDeferrableCallback;
@@ -26,7 +27,8 @@
 import java.util.Objects;
 
 /**
- * Command that displays the top helpers of a given time range.
+ * Command that displays the top helpers of a given time range. Can also be used to start a
+ * semi-automatic flow to assign Top Helpers.
  * <p>
  * Top helpers are measured by their message length in help channels, as set by
  * {@link TopHelpersMessageListener}.
@@ -57,12 +59,12 @@ public TopHelpersCommand(TopHelpersService service,
             .forEach(month -> monthData.addChoice(
                     month.getDisplayName(TextStyle.FULL_STANDALONE, Locale.US), month.name()));
 
-        getData().addSubcommands(
-                new SubcommandData(SUBCOMMAND_SHOW_NAME,
-                        "Lists top helpers for the last month, or a given month")
-                    .addOptions(monthData),
-                new SubcommandData(SUBCOMMAND_ASSIGN_NAME,
-                        "Automatically assigns top helpers for the last month"));
+        var showCommand = new SubcommandData(SUBCOMMAND_SHOW_NAME,
+                "Lists top helpers for the last month, or a given month")
+            .addOptions(monthData);
+        var assignCommand = new SubcommandData(SUBCOMMAND_ASSIGN_NAME,
+                "Automatically assigns top helpers for the last month");
+        getData().addSubcommands(showCommand, assignCommand);
 
         this.service = service;
         this.assignmentRoutine = assignmentRoutine;
@@ -80,11 +82,12 @@ public void onSlashCommand(SlashCommandInteractionEvent event) {
 
     private void showTopHelpers(SlashCommandInteractionEvent event) {
         OptionMapping atMonthData = event.getOption(MONTH_OPTION);
+        Guild guild = Objects.requireNonNull(event.getGuild());
 
         TopHelpersService.TimeRange timeRange =
-                TopHelpersService.TimeRange.ofMonth(computeMonth(atMonthData));
-        List<TopHelpersService.TopHelperResult> topHelpers = service.computeTopHelpersDescending(
-                event.getGuild().getIdLong(), timeRange.start(), timeRange.end());
+                TopHelpersService.TimeRange.ofPastMonth(computeMonth(atMonthData));
+        List<TopHelpersService.TopHelperStats> topHelpers =
+                service.computeTopHelpersDescending(guild, timeRange);
 
         if (topHelpers.isEmpty()) {
             event
@@ -95,7 +98,7 @@ private void showTopHelpers(SlashCommandInteractionEvent event) {
         }
         event.deferReply().queue();
 
-        service.retrieveTopHelperMembers(topHelpers, event.getGuild())
+        TopHelpersService.retrieveTopHelperMembers(topHelpers, guild)
             .onError(error -> handleError(error, event))
             .onSuccess(members -> handleTopHelpers(topHelpers, members, timeRange, event));
     }
@@ -121,15 +124,15 @@ private static void handleError(Throwable error, IDeferrableCallback event) {
         event.getHook().editOriginal("Sorry, something went wrong.").queue();
     }
 
-    private void handleTopHelpers(Collection<TopHelpersService.TopHelperResult> topHelpers,
+    private void handleTopHelpers(Collection<TopHelpersService.TopHelperStats> topHelpers,
             Collection<? extends Member> members, TopHelpersService.TimeRange timeRange,
             IDeferrableCallback event) {
         String message = """
                 ```java
                 // for %s
                 %s
                 ```""".formatted(timeRange.description(),
-                service.asAsciiTable(topHelpers, members, true));
+                TopHelpersService.asAsciiTableWithIds(topHelpers, members));
         event.getHook().editOriginal(message).queue();
     }
 }