Javadoc, Linter

Author: Zabuzard

application/src/main/java/org/togetherjava/tjbot/commands/moderation/BanCommand.java

@@ -45,6 +45,7 @@ public final class BanCommand extends SlashCommandAdapter {
     private static final String REASON_OPTION = "reason";
     private static final String COMMAND_NAME = "ban";
     private static final String ACTION_VERB = "ban";
+    @SuppressWarnings("StaticCollection")
     private static final List<String> DURATIONS = List.of(ModerationUtils.PERMANENT_DURATION,
             "1 hour", "3 hours", "1 day", "2 days", "3 days", "7 days", "30 days");
     private final Predicate<String> hasRequiredRole;
@@ -152,6 +153,7 @@ private RestAction<InteractionHook> banUserFlow(@NotNull User target, @NotNull M
             .flatMap(event::replyEmbeds);
     }
 
+    @SuppressWarnings("MethodWithTooManyParameters")
     private AuditableRestAction<Void> banUser(@NotNull User target, @NotNull Member author,
             @Nullable ModerationUtils.TemporaryData temporaryData, @NotNull String reason,
             int deleteHistoryDays, @NotNull Guild guild) {

application/src/main/java/org/togetherjava/tjbot/commands/moderation/ModerationActionsStore.java

@@ -39,7 +39,12 @@ public ModerationActionsStore(@NotNull Database database) {
         this.database = Objects.requireNonNull(database);
     }
 
-    // FIXME javadoc
+    /**
+     * Gets all already expired actions, measured by the current time, which have been written to
+     * the store, chronologically ascending with the action issued the earliest first.
+     * 
+     * @return a list of all expired actions, chronologically ascending
+     */
     public @NotNull List<ActionRecord> getExpiredActionsAscending() {
         return getActionsAscendingWhere(
                 ModerationActions.MODERATION_ACTIONS.ACTION_EXPIRES_AT.isNotNull()
@@ -92,7 +97,16 @@ public ModerationActionsStore(@NotNull Database database) {
                 ModerationActions.MODERATION_ACTIONS.AUTHOR_ID.eq(authorId));
     }
 
-    // FIXME javadoc
+    /**
+     * Gets the action of the given type that was issued the latest against the given target, if
+     * present.
+     * 
+     * @param guildId the id of the guild, only actions that happened in the context of that guild
+     *        will be retrieved
+     * @param targetId the id of the target user to filter for
+     * @param actionType the type of the action
+     * @return the last action issued against the given user of the given type, if present
+     */
     public @NotNull Optional<ActionRecord> findLastActionAgainstTargetByType(long guildId,
             long targetId, @NotNull ModerationAction actionType) {
         return database

application/src/main/java/org/togetherjava/tjbot/commands/moderation/ModerationUtils.java

@@ -30,10 +30,20 @@ public enum ModerationUtils {
      * {@link Guild#ban(User, int, String)}.
      */
     private static final int REASON_MAX_LENGTH = 512;
-    // FIXME Javadoc
+    /**
+     * Human-readable text representing the duration of a permanent action, will be shown to the
+     * user as option for selection.
+     */
     static final String PERMANENT_DURATION = "permanent";
+    /**
+     * The ambient color used by moderation actions, often used to streamline the color theme of
+     * embeds.
+     */
     static final Color AMBIENT_COLOR = Color.decode("#895FE8");
-    // FIXME Javadoc
+    /**
+     * Matches the name of the role that is used to mute users, as used by {@link MuteCommand} and
+     * similar.
+     */
     public static final Predicate<String> isMuteRole =
             Pattern.compile(Config.getInstance().getMutedRolePattern()).asMatchPredicate();
 
@@ -331,6 +341,15 @@ static boolean handleHasAuthorRole(@NotNull String actionVerb,
         return guild.getRoles().stream().filter(role -> isMuteRole.test(role.getName())).findAny();
     }
 
+    /**
+     * Computes a temporary data wrapper representing the action with the given duration.
+     *
+     * @param durationText the duration of the action, either {@code "permanent"} or a time window
+     *        such as {@code 1 day} or {@code 2 minutes}. Supports all units supported by
+     *        {@link Instant#plus(long, TemporalUnit)}.
+     * @return the temporary data represented by the given duration or empty if the duration is
+     *         {@code "permanent"}
+     */
     static @NotNull Optional<TemporaryData> computeTemporaryData(@NotNull String durationText) {
         if (PERMANENT_DURATION.equals(durationText)) {
             return Optional.empty();
@@ -350,6 +369,13 @@ static boolean handleHasAuthorRole(@NotNull String actionVerb,
         return Optional.of(new TemporaryData(Instant.now().plus(duration, unit), durationText));
     }
 
+    /**
+     * Wrapper to hold data relevant to temporary actions, for example the time it expires.
+     *
+     * @param expiresAt the time the temporary action expires
+     * @param duration a human-readable text representing the duration of the temporary action, such
+     *        as {@code "1 day"}.
+     */
     record TemporaryData(@NotNull Instant expiresAt, @NotNull String duration) {
     }
 }

application/src/main/java/org/togetherjava/tjbot/commands/moderation/MuteCommand.java

@@ -38,6 +38,7 @@ public final class MuteCommand extends SlashCommandAdapter {
     private static final String REASON_OPTION = "reason";
     private static final String COMMAND_NAME = "mute";
     private static final String ACTION_VERB = "mute";
+    @SuppressWarnings("StaticCollection")
     private static final List<String> DURATIONS = List.of("10 minutes", "30 minutes", "1 hour",
             "3 hours", "1 day", "3 days", "7 days", ModerationUtils.PERMANENT_DURATION);
     private final Predicate<String> hasRequiredRole;
@@ -119,6 +120,7 @@ private AuditableRestAction<Void> muteUser(@NotNull Member target, @NotNull Memb
             .reason(reason);
     }
 
+    @SuppressWarnings("MethodWithTooManyParameters")
     private void muteUserFlow(@NotNull Member target, @NotNull Member author,
             @Nullable ModerationUtils.TemporaryData temporaryData, @NotNull String reason,
             @NotNull Guild guild, @NotNull SlashCommandEvent event) {

application/src/main/java/org/togetherjava/tjbot/commands/moderation/temp/RevocableModerationAction.java

@@ -6,23 +6,67 @@
 import org.jetbrains.annotations.NotNull;
 import org.togetherjava.tjbot.commands.moderation.ModerationAction;
 
-// FIXME Javadoc
+/**
+ * Represents revocable moderation actions, such as temporary bans. Primarily used by
+ * {@link TemporaryModerationRoutine} to identify and revoke such actions.
+ */
 interface RevocableModerationAction {
+    /**
+     * Classification of a revocation failure.
+     */
+    @SuppressWarnings("PublicInnerClass")
     enum FailureIdentification {
+        /**
+         * Acknowledges that the failure is known and has been handled. Hence, further error
+         * handling should not be continued.
+         */
         KNOWN,
+        /**
+         * The failure is unknown and has not been handled. Hence, further error handling should be
+         * continued.
+         */
         UNKNOWN
     }
 
+    /**
+     * The type to apply the temporary action, such as
+     * {@link net.dv8tion.jda.api.audit.ActionType#BAN}.
+     * 
+     * @return the type to apply the temporary action
+     */
     @NotNull
     ModerationAction getApplyType();
 
+    /**
+     * The type to revoke the temporary action, such as
+     * {@link net.dv8tion.jda.api.audit.ActionType#UNBAN}.
+     * 
+     * @return the type to revoke the temporary action
+     */
     @NotNull
     ModerationAction getRevokeType();
 
+    /**
+     * Revokes the temporary action against the given target.
+     * 
+     * @param guild the guild the user belongs to
+     * @param target the target to revoke the action against
+     * @param reason why the action is revoked
+     * @return the unsubmitted revocation action
+     */
     @NotNull
     RestAction<Void> revokeAction(@NotNull Guild guild, @NotNull User target,
             @NotNull String reason);
 
+    /**
+     * Handle a failure that might occur during revocation, i.e. execution of the action returned by
+     * {@link #revokeAction(Guild, User, String)}.
+     * 
+     * @param failure the failure to handle
+     * @param targetId the id of the user who is targeted by the revocation
+     * @return a classification of the failure, decides whether the surrounding flow will continue
+     *         to handle the error further or not
+     */
     @NotNull
     FailureIdentification handleRevokeFailure(@NotNull Throwable failure, long targetId);
 }

application/src/main/java/org/togetherjava/tjbot/commands/moderation/temp/TemporaryBanAction.java

@@ -10,7 +10,11 @@
 import org.slf4j.LoggerFactory;
 import org.togetherjava.tjbot.commands.moderation.ModerationAction;
 
-// FIXME Javadoc
+/**
+ * Action to revoke temporary bans, as applied by
+ * {@link org.togetherjava.tjbot.commands.moderation.BanCommand} and executed by
+ * {@link TemporaryModerationRoutine}.
+ */
 final class TemporaryBanAction implements RevocableModerationAction {
     private static final Logger logger = LoggerFactory.getLogger(TemporaryBanAction.class);
 

application/src/main/java/org/togetherjava/tjbot/commands/moderation/temp/TemporaryModerationRoutine.java

@@ -21,7 +21,16 @@
 import java.util.stream.Collectors;
 import java.util.stream.Stream;
 
-// FIXME javadoc
+/**
+ * Routine that revokes temporary moderation actions, such as temporary bans, as listed by
+ * {@link ModerationActionsStore}.
+ * <p>
+ * The routine is started by using {@link #start()} and then automatically executes on a schedule.
+ * <p>
+ * Revoked actions are compatible with {@link ModerationActionsStore} and commands such as
+ * {@link org.togetherjava.tjbot.commands.moderation.UnbanCommand} and
+ * {@link org.togetherjava.tjbot.commands.moderation.AuditCommand}.
+ */
 public final class TemporaryModerationRoutine {
     private static final Logger logger = LoggerFactory.getLogger(TemporaryModerationRoutine.class);
 
@@ -142,15 +151,15 @@ private void handleFailure(@NotNull Throwable failure,
     public void start() {
         // TODO This should be registered at some sort of routine system instead (see GH issue #235
         // which adds support for routines)
-        // NOTE The initial run has to be delayed until after the guild cache has been updated
+        // TODO The initial run has to be delayed until after the guild cache has been updated
         // (during CommandSystem startup)
         checkExpiredActionsService.scheduleWithFixedDelay(this::checkExpiredActions, 5, 5,
                 TimeUnit.MINUTES);
     }
 
     private record RevocationGroupIdentifier(long guildId, long targetId,
             @NotNull ModerationAction type) {
-        public static RevocationGroupIdentifier of(@NotNull ActionRecord actionRecord) {
+        static RevocationGroupIdentifier of(@NotNull ActionRecord actionRecord) {
             return new RevocationGroupIdentifier(actionRecord.guildId(), actionRecord.targetId(),
                     actionRecord.actionType());
         }

application/src/main/java/org/togetherjava/tjbot/commands/moderation/temp/TemporaryMuteAction.java

@@ -11,7 +11,11 @@
 import org.togetherjava.tjbot.commands.moderation.ModerationAction;
 import org.togetherjava.tjbot.commands.moderation.ModerationUtils;
 
-// FIXME Javadoc
+/**
+ * Action to revoke temporary mutes, as applied by
+ * {@link org.togetherjava.tjbot.commands.moderation.MuteCommand} and executed by
+ * {@link TemporaryModerationRoutine}.
+ */
 final class TemporaryMuteAction implements RevocableModerationAction {
     private static final Logger logger = LoggerFactory.getLogger(TemporaryMuteAction.class);
 
@@ -37,13 +41,12 @@ final class TemporaryMuteAction implements RevocableModerationAction {
     @Override
     public @NotNull FailureIdentification handleRevokeFailure(@NotNull Throwable failure,
             long targetId) {
-        if (failure instanceof ErrorResponseException errorResponseException) {
-            if (errorResponseException.getErrorResponse() == ErrorResponse.UNKNOWN_USER) {
-                logger.info(
-                        "Attempted to revoke a temporary mute but user '{}' does not exist anymore.",
-                        targetId);
-                return FailureIdentification.KNOWN;
-            }
+        if (failure instanceof ErrorResponseException errorResponseException
+                && errorResponseException.getErrorResponse() == ErrorResponse.UNKNOWN_USER) {
+            logger.info(
+                    "Attempted to revoke a temporary mute but user '{}' does not exist anymore.",
+                    targetId);
+            return FailureIdentification.KNOWN;
         }
         return FailureIdentification.UNKNOWN;
     }