Merge pull request #1 from HawkDiscord/feature/docs

Add docs where missing

Author: DRSchlaubi

common/src/main/java/me/schlaubi/regnumutils/common/Misc.java

@@ -19,15 +19,25 @@
 
 package me.schlaubi.regnumutils.common;
 
+import org.jetbrains.annotations.NotNull;
 import org.jetbrains.annotations.Nullable;
 
 import java.util.Collection;
 import java.util.List;
 
+/**
+ * Some tools.
+ */
 public class Misc {
 
+    /**
+     * Returns the first element of a {@link Collection}.
+     * @param collection the collection
+     * @param <T> the type of the elements
+     * @return the element or {@code null} if the collection is empty
+     */
     @Nullable
-    public static <T> T first(Collection<T> collection) {
+    public static <T> T first(@NotNull Collection<T> collection) {
         if (collection.isEmpty()) {
             return null;
         }
@@ -38,7 +48,12 @@ public static <T> T first(Collection<T> collection) {
         }
     }
 
-    public static boolean isNumeric(String input) {
+    /**
+     * Checks whether a String is numeric or not.
+     * @param input the string to check
+     * @return whether a String is numeric or not
+     */
+    public static boolean isNumeric(@NotNull String input) {
         return input
                 .chars()
                 .mapToObj(it -> (char) it)

common/src/main/java/me/schlaubi/regnumutils/common/builder/GameAnimatorBuilder.java

@@ -241,6 +241,7 @@ public TimeUnit getTimeUnit() {
      * @see GameAnimatorBuilder#setInterval(long)
      * @see GameAnimatorBuilder#setInitialDelay(long)
      */
+    @SuppressWarnings("UnusedReturnValue")
     @NotNull
     public GameAnimatorBuilder setTimeUnit(@NotNull TimeUnit unit) {
         this.unit = unit;
@@ -266,7 +267,6 @@ public GameAnimatorBuilder setJDA(JDA jda) {
      * @return the {@link GameAnimatorBuilder}
      * @see GameAnimatorBuilder#setApplier(Consumer)
      */
-
     @NotNull
     public GameAnimatorBuilder setShardManager(ShardManager shardManager) {
         return setApplier((game) -> JDAExtensions.applyGame(shardManager, game));

common/src/main/java/me/schlaubi/regnumutils/common/formatting/FormatUtil.java

@@ -22,6 +22,9 @@
 import net.dv8tion.jda.api.entities.MessageEmbed;
 import org.jetbrains.annotations.NotNull;
 
+/**
+ * Some useful formatting helpers.
+ */
 public class FormatUtil {
 
     /**

common/src/main/java/me/schlaubi/regnumutils/common/messaging/SafeMessage.java

@@ -42,6 +42,9 @@
 import java.util.function.Consumer;
 import java.util.function.Supplier;
 
+/**
+ * Util to send messages safely without risking {@link InsufficientPermissionException}s
+ */
 @SuppressWarnings({"unused", "WeakerAccess"})
 public class SafeMessage {
 

common/src/main/java/me/schlaubi/regnumutils/common/parsing/EntityResolver.java

@@ -30,13 +30,13 @@
 import java.util.function.Function;
 
 /**
- * Useful tool to parse a text-message for EntityResolvable
+ * Useful tool to parse a text-message for EntityResolvable.
  */
 @SuppressWarnings({"unused", "WeakerAccess"})
 public class EntityResolver {
 
     /**
-     * Resolves an {@link User} entity by a mention, it's id or it's name (case-sensitive)
+     * Resolves an {@link User} entity by a mention, it's id or it's name (case-sensitive).
      *
      * @param input e.g an user input that should get parsed for mentions
      * @param jda the {@link JDA} instance of you bot
@@ -51,7 +51,7 @@ public static User resolveUser(
     }
 
     /**
-     * Resolves an {@link TextChannel} entity by a mention, it's id or it's name
+     * Resolves an {@link TextChannel} entity by a mention, it's id or it's name.
      *
      * @param input e.g an user input that should get parsed for mentions
      * @param jda the {@link JDA} instance of you bot
@@ -69,7 +69,7 @@ public static User resolveUser(
 
 
     /**
-     * Resolves an {@link Role} entity by a mention, it's id or it's name (case-sensitive)
+     * Resolves an {@link Role} entity by a mention, it's id or it's name (case-sensitive).
      *
      * @param input e.g an user input that should get parsed for mentions
      * @param guild the {@link Guild} the member is on
@@ -84,7 +84,7 @@ public static Member resolveMember(
     }
 
     /**
-     * Resolves an {@link TextChannel} entity by a mention, it's id or it's name
+     * Resolves an {@link TextChannel} entity by a mention, it's id or it's name.
      *
      * @param input e.g an user input that should get parsed for mentions
      * @param guild the {@link Guild} the member is on
@@ -101,7 +101,7 @@ public static Member resolveMember(
     }
 
     /**
-     * Resolves an {@link TextChannel} entity by a mention, it's id or it's name (case-sensitive)
+     * Resolves an {@link TextChannel} entity by a mention, it's id or it's name (case-sensitive).
      *
      * @param input e.g an user input that should get parsed for mentions
      * @param guild the {@link Guild} the channel is on
@@ -116,7 +116,7 @@ public static TextChannel resolveTextChannel(
     }
 
     /**
-     * Resolves an {@link TextChannel} entity by a mention, it's id or it's name
+     * Resolves an {@link TextChannel} entity by a mention, it's id or it's name.
      *
      * @param input e.g an user input that should get parsed for mentions
      * @param guild the {@link Guild} the channel is on
@@ -133,7 +133,7 @@ public static TextChannel resolveTextChannel(
     }
 
     /**
-     * Resolves an {@link Role} entity by a mention, it's id or it's name (case-sensitive)
+     * Resolves an {@link Role} entity by a mention, it's id or it's name (case-sensitive).
      *
      * @param input e.g an user input that should get parsed for mentions
      * @param guild the {@link Guild} the role is on
@@ -148,7 +148,7 @@ public static Role resolveRole(
     }
 
     /**
-     * Resolves an {@link Role} entity by a mention, it's id or it's name
+     * Resolves an {@link Role} entity by a mention, it's id or it's name.
      *
      * @param input e.g an user input that should get parsed for mentions
      * @param guild the {@link Guild} the role is on
@@ -165,7 +165,7 @@ public static Role resolveRole(
     }
 
     /**
-     * Resolves an {@link IMentionable mentionable} entity by a mention, it's id or it's name (case-sensitive)
+     * Resolves an {@link IMentionable mentionable} entity by a mention, it's id or it's name (case-sensitive).
      *
      * @param input e.g an user input that should get parsed for mentions
      * @param type the {@link net.dv8tion.jda.api.entities.Message.MentionType} of the expected entity
@@ -179,13 +179,13 @@ public static <T extends IMentionable> T resolveEntity(
             @NotNull String input,
             @NotNull Message.MentionType type,
             @NotNull Function<@NotNull String, @Nullable T> idResolver,
-            @NotNull BiFunction<@NotNull String, Boolean, @Nullable Collection<T>> nameResolver
+            @NotNull BiFunction<@NotNull String, Boolean, @NotNull Collection<T>> nameResolver
     ) {
         return resolveEntity(input, type, idResolver, nameResolver, false);
     }
 
     /**
-     * Resolves an {@link IMentionable mentionable} entity by a mention, it's id or it's name
+     * Resolves an {@link IMentionable mentionable} entity by a mention, it's id or it's name.
      *
      * @param input e.g an user input that should get parsed for mentions
      * @param type the {@link net.dv8tion.jda.api.entities.Message.MentionType} of the expected entity
@@ -200,7 +200,7 @@ public static <T extends IMentionable> T resolveEntity(
             @NotNull String input,
             @NotNull Message.MentionType type,
             @NotNull Function<@NotNull String, @Nullable T> idResolver,
-            @NotNull BiFunction<@NotNull String, Boolean, @Nullable Collection<T>> nameResolver,
+            @NotNull BiFunction<@NotNull String, Boolean, @NotNull Collection<T>> nameResolver,
             boolean ignoreCase
     ) {
         if (input.isBlank() || input.isEmpty()) {

common/src/main/kotlin/me/schlaubi/regnumutils/common/jda/_JDAExtensions.kt

@@ -28,32 +28,67 @@ import net.dv8tion.jda.api.OnlineStatus
 import net.dv8tion.jda.api.entities.Activity
 import net.dv8tion.jda.api.sharding.ShardManager
 
+/**
+ * The [JDA] instance used by the [cc.hawkbot.regnum.client.core.discord.ShardManager].
+ * @see JDAShardManager
+ */
 val cc.hawkbot.regnum.client.core.discord.ShardManager.jda: ShardManager
     get() = (this as JDAShardManager).jda
 
+/**
+ * Converts a [GameAnimator.Game] to an [Activity] object which can be used for changing a [jda presence][net.dv8tion.jda.api.managers.Presence]
+ * @see Activity
+ */
 fun GameAnimator.Game.toActivity() = Activity.of(Activity.ActivityType.fromKey(type), content)
 
+/**
+ * Converts a [GameAnimator.Game] to an [OnlineStatus] object which can be used for changing a [jda presence][net.dv8tion.jda.api.managers.Presence]
+ * @see OnlineStatus
+ */
 val GameAnimator.Game.onlineStatus: OnlineStatus
     get() = OnlineStatus.fromKey(status)
 
+/**
+ * Applies a [GameAnimator.Game] to a a [jda presence][net.dv8tion.jda.api.managers.Presence]
+ * @see net.dv8tion.jda.api.managers.Presence
+ */
 fun JDA.applyGame(game: GameAnimator.Game) = presence.setPresence(game.onlineStatus, game.toActivity())
 
+/**
+ * Applies a [GameAnimator.Game] to a a [jda presence][net.dv8tion.jda.api.managers.Presence]
+ * @see net.dv8tion.jda.api.managers.Presence
+ */
 fun ShardManager.applyGame(game: GameAnimator.Game) = setPresence(game.onlineStatus, game.toActivity())
 
 object JDAExtensions {
 
+    /**
+     * @see cc.hawkbot.regnum.client.core.discord.ShardManager.jda
+     */
     @JvmStatic
     fun jda(shardManager: cc.hawkbot.regnum.client.core.discord.ShardManager) = shardManager.jda
 
+    /**
+     * @see GameAnimator.Game.toActivity
+     */
     @JvmStatic
     fun gameToActivity(game: GameAnimator.Game) = game.toActivity()
 
+    /**
+     * @see GameAnimator.Game.onlineStatus
+     */
     @JvmStatic
     fun gameToOnlineStatus(game: GameAnimator.Game) = game.onlineStatus
 
+    /**
+     * @see JDA.applyGame
+     */
     @JvmStatic
     fun applyGame(jda: JDA, game: GameAnimator.Game) = jda.applyGame(game)
 
+    /**
+     * @see ShardManager.applyGame
+     */
     @JvmStatic
     fun applyGame(jda: ShardManager, game: GameAnimator.Game) = jda.applyGame(game)
 }