add Javadoc comments

Author: danthe1st

src/main/java/net/discordjug/javabot/systems/color_roles/ChangeColorCommand.java

@@ -18,18 +18,26 @@
 import xyz.dynxsty.dih4jda.interactions.commands.application.SlashCommand;
 import xyz.dynxsty.dih4jda.util.AutoCompleteUtils;
 
+/**
+ * The {@code /color} command which allows users to change their own color with color roles.
+ */
 public class ChangeColorCommand extends SlashCommand implements AutoCompletable {
 
 	private static final Pattern COLOR_PATTERN = Pattern.compile("#[A-F0-9]{6}", Pattern.CASE_INSENSITIVE);
 
 	private final BotConfig config;
 	private final ColorRoleService service;
 
+	/**
+	 * The constructor which sets the corresponding {@link net.dv8tion.jda.api.interactions.commands.build.SlashCommandData}.
+	 * @param botConfig The bot's configuration
+	 * @param service The {@link ColorRoleService} to actually change color roles
+	 */
 	public ChangeColorCommand(BotConfig botConfig, ColorRoleService service) {
 		this.config = botConfig;
 		this.service = service;
 		setCommandData(Commands.slash("color", "Sets the color of your roles")
-				.addOption(OptionType.STRING, "color", "The hex code of the role color", false, true));
+				.addOption(OptionType.STRING, "color", "The hex code of the role color (leave empty to remove your color roles)", false, true));
 	}
 
 	@Override

src/main/java/net/discordjug/javabot/systems/color_roles/ColorRole.java

@@ -1,7 +1,18 @@
 package net.discordjug.javabot.systems.color_roles;
 
 import java.awt.Color;
+import java.util.Objects;
 
+/**
+ * A self-assignable color role.
+ * @param guildId The Discord ID of the guild the role is a part of
+ * @param roleId The Discord ID of the role
+ * @param color The color of the role
+ * @see ChangeColorCommand
+ * @see ColorRoleService
+ */
 public record ColorRole(long guildId, long roleId, Color color) {
-
+	public ColorRole {
+		Objects.requireNonNull(color);
+	}
 }

src/main/java/net/discordjug/javabot/systems/color_roles/ColorRoleService.java

@@ -13,6 +13,11 @@
 import net.dv8tion.jda.api.hooks.ListenerAdapter;
 import org.springframework.stereotype.Service;
 
+/**
+ * Service class for assigning and removing color roles.
+ * @see ColorRoleService#addColor(Member, Color)
+ * @see ColorRoleService#removeColor(Member)
+ */
 @Service
 public class ColorRoleService extends ListenerAdapter {
 
@@ -24,6 +29,13 @@ public ColorRoleService(ColorRoleRepository repo, BotConfig config) {
 		this.config = config;
 	}
 
+	/**
+	 * Adds a color role to a user.
+	 * 
+	 * If a color role with the given color exists already, it will be reused. Otherwise, it will create a new one.
+	 * @param member The member to add the role to
+	 * @param color The color of the role to assign
+	 */
 	public synchronized void addColor(Member member, Color color) {
 		repo.getFromColor(member.getGuild().getIdLong(), color)
 			.ifPresentOrElse(colorRole -> {
@@ -44,6 +56,13 @@ public synchronized void addColor(Member member, Color color) {
 			});
 	}
 
+	/**
+	 * Removes all color roles from a user.
+	 * 
+	 * If no other members have that role, the role will be deleted.
+	 * @param member The member to remove the role from
+	 * @return {@code true} if any color roles were removed, else {@code false}
+	 */
 	public synchronized boolean removeColor(Member member) {
 		boolean changed = false;
 		for (ColorRole color : repo.getColorRolesOfMember(member.getGuild().getIdLong(), member.getIdLong())) {

src/main/java/net/discordjug/javabot/systems/color_roles/dao/ColorRoleRepository.java

@@ -4,34 +4,56 @@
 import java.util.List;
 import java.util.Optional;
 
+import javax.annotation.CheckReturnValue;
+
 import lombok.RequiredArgsConstructor;
 import net.discordjug.javabot.systems.color_roles.ColorRole;
 import org.springframework.dao.EmptyResultDataAccessException;
 import org.springframework.jdbc.core.JdbcTemplate;
 import org.springframework.stereotype.Repository;
 
+/**
+ * Repository class for the COLOR_ROLES and COLOR_ROLE_MEMBERS tables which are used for role colors.
+ */
 @Repository
 @RequiredArgsConstructor
 public class ColorRoleRepository {
 	private final JdbcTemplate jdbcTemplate;
 
+	/**
+	 * Gets all color roles of a guild.
+	 * @param guildId The ID of the guild
+	 * @return A {@link List} of all registered role colors in the guild
+	 */
 	public List<ColorRole> getColorRoles(long guildId) {
 		return jdbcTemplate.query("SELECT ROLE_ID, COLOR FROM COLOR_ROLES WHERE GUILD_ID=?",
 				(rs, _) -> new ColorRole(guildId, rs.getLong(1), new Color(rs.getInt(2))),
 				guildId);
 	}
 
+	/**
+	 * Tries to find a color role given the color.
+	 * @param guildId The ID of the guild containing the role
+	 * @param color The color of the role to search for
+	 * @return The color role if it exists or {@link Optional#empty()}
+	 */
 	public Optional<ColorRole> getFromColor(long guildId, Color color) {
 		try {
 			ColorRole result = jdbcTemplate.queryForObject("SELECT ROLE_ID FROM COLOR_ROLES WHERE GUILD_ID=? AND COLOR=?",
-					((rs, _) -> new ColorRole(guildId, rs.getLong(1), color)),
+					(rs, _) -> new ColorRole(guildId, rs.getLong(1), color),
 					guildId, color.getRGB());
 			return Optional.ofNullable(result);
 		} catch(EmptyResultDataAccessException _) {
 			return Optional.empty();
 		}
 	}
 
+	/**
+	 * Gets all color roles of a given member.
+	 * @param guildId The ID of the guild the roles should be part of
+	 * @param memberId The ID of the member get the roles of
+	 * @return All color roles of the given member in the given guild
+	 */
 	public List<ColorRole> getColorRolesOfMember(long guildId, long memberId) {
 		return jdbcTemplate.query("""
 				SELECT cr.ROLE_ID, cr.COLOR
@@ -43,19 +65,44 @@ public List<ColorRole> getColorRolesOfMember(long guildId, long memberId) {
 				guildId, memberId);
 	}
 
+	/**
+	 * Registers that a member has a given color role.
+	 * @param color The color role
+	 * @param memberId The member the role is being added to
+	 */
 	public void addColorRole(ColorRole color, long memberId) {
 		jdbcTemplate.update("INSERT INTO COLOR_ROLES (ROLE_ID, GUILD_ID, COLOR) VALUES (?,?,?)",
 				color.roleId(), color.guildId(), color.color().getRGB());
-		jdbcTemplate.update("INSERT INTO COLOR_ROLE_MEMBERS (ROLE_ID, USER_ID) VALUES (?, ?)", color.roleId(), memberId);
+		addRoleToMember(color.roleId(), memberId);
 	}
 
+	/**
+	 * Registers that a color role has been added to a member.
+	 * @param roleId The ID of the role the member has
+	 * @param memberId The ID of the member to update
+	 */
 	public void addRoleToMember(long roleId, long memberId) {
 		jdbcTemplate.update("INSERT INTO COLOR_ROLE_MEMBERS (ROLE_ID, USER_ID) VALUES (?,?)", roleId, memberId);
 	}
+	
+	/**
+	 * Registers that a color role has been added to a member.
+	 * @param roleId The ID of the role removed from the member
+	 * @param memberId The ID of the member to update
+	 * @see #cleanRoleIfNoMembers(long)
+	 */
 	public void removeRoleFromMember(long roleId, long memberId) {
 		jdbcTemplate.update("DELETE FROM COLOR_ROLE_MEMBERS WHERE ROLE_ID=? AND USER_ID=?", roleId, memberId);
 	}
 
+	/**
+	 * Removes a role from the database if it has no members.
+	 * 
+	 * Callers should make sure to actually delete the role if this method returns {@code true}.
+	 * @param roleId The ID of the role to possibly remove
+	 * @return {@code true} if the role is registered as removed due to not having any members, else {@code false}
+	 */
+	@CheckReturnValue
 	public boolean cleanRoleIfNoMembers(long roleId) {
 		return jdbcTemplate.update("DELETE FROM COLOR_ROLES WHERE ROLE_ID=? AND (SELECT COUNT(*) FROM COLOR_ROLE_MEMBERS WHERE ROLE_ID=?)=0", roleId, roleId) > 0;
 	}