commands.kt documentation updated

ileukocyte · Aug 12, 2022 · 58cf42a · 58cf42a
1 parent 937c0bd
commit 58cf42a
Show file tree

Hide file tree

Showing 8 changed files with 58 additions and 24 deletions.
diff --git a/src/main/kotlin/io/ileukocyte/hibernum/commands/commands.kt b/src/main/kotlin/io/ileukocyte/hibernum/commands/commands.kt
@@ -39,11 +39,21 @@ import org.jetbrains.kotlin.utils.addToStdlib.applyIf
  */
 interface GenericCommand : Comparable<GenericCommand> {
     /**
+     * A property that provides the main name of the command
+     *
      * **Note**: the property is always mandatory to override unless the command is a context-menu one;
      * therefore, do not forget to override it yourself in case the command is not context menu only!
      */
     val name: String
+
+    /**
+     * A property that provides the main description of the command
+     */
     val description: String
+
+    /**
+     * A property that provides the functional category of the command
+     */
     val category: CommandCategory
         get() = javaClass.`package`.name.let { CommandCategory[it.split(".").last()] }
             ?: CommandCategory.UNKNOWN
@@ -69,12 +79,15 @@ interface GenericCommand : Comparable<GenericCommand> {
         get() = category == CommandCategory.DEVELOPER
 
     /**
-     * Used for a few commands that can be used in spite of some other command processes
+     * Used for a few commands that can be used in spite of any other command processes
      * running in the background
      */
     val neglectProcessBlock: Boolean
         get() = isDeveloper
 
+    /**
+     * A property that provides all the ways the current command can be used by a user
+     */
     val inputTypes: Set<InputType>
         get() {
             val inputTypes = mutableSetOf<InputType>()
@@ -102,19 +115,33 @@ interface GenericCommand : Comparable<GenericCommand> {
             return inputTypes
         }
 
+    /**
+     * A property that provides the minimum length of time that a user will need to wait after using the command
+     * before it can be used again
+     */
     val cooldown: Long
         get() = 0
 
     /**
-     * A property that shows whether the command's expired interactions should
+     * A property that shows whether the command's expired components should
      * trigger an explicit failure response, silent deletion of the command's
      * components (i.e. buttons and selection menus), or normal execution of the command
+     *
+     * **Note**: A component is considered expired within the project if it was sent by the bot
+     * before the latest reboot
      */
-    val staleInteractionHandling: StaleInteractionHandling
-        get() = StaleInteractionHandling.DELETE_ORIGINAL
+    val staleComponentHandling: StaleComponentHandling
+        get() = StaleComponentHandling.DELETE_ORIGINAL
 
+    /**
+     * A property that provides a set of the permissions that the bot is required to have to execute the command
+     */
     val botPermissions: Set<Permission>
         get() = emptySet()
+
+    /**
+     * A property that provides a set of the permissions that the user is required to have to execute the command
+     */
     val memberPermissions: Set<Permission>
         get() = emptySet()
 
@@ -158,7 +185,7 @@ interface GenericCommand : Comparable<GenericCommand> {
         }
     }
 
-    enum class StaleInteractionHandling {
+    enum class StaleComponentHandling {
         DELETE_ORIGINAL,
         REMOVE_COMPONENTS,
         EXECUTE_COMMAND,
@@ -335,7 +362,14 @@ interface ContextCommand : GenericCommand {
     override val name: String
         get() = contextName
 
+    /**
+     * A property that provides the context-menu name of the command
+     */
     val contextName: String
+
+    /**
+     * A property that provides a set of context menus a user is able to invoke the command from
+     */
     val contextTypes: Set<ContextType>
         get() = setOf(ContextType.MESSAGE, ContextType.USER)
 

diff --git a/src/main/kotlin/io/ileukocyte/hibernum/commands/developer/ProcessesCommand.kt b/src/main/kotlin/io/ileukocyte/hibernum/commands/developer/ProcessesCommand.kt
@@ -5,7 +5,7 @@ import com.google.common.collect.Lists
 import io.ileukocyte.hibernum.Immutable
 import io.ileukocyte.hibernum.builders.buildEmbed
 import io.ileukocyte.hibernum.commands.CommandException
-import io.ileukocyte.hibernum.commands.GenericCommand.StaleInteractionHandling
+import io.ileukocyte.hibernum.commands.GenericCommand.StaleComponentHandling
 import io.ileukocyte.hibernum.commands.SlashOnlyCommand
 import io.ileukocyte.hibernum.commands.`fun`.AkinatorCommand
 import io.ileukocyte.hibernum.commands.`fun`.ChomskyCommand
@@ -45,7 +45,7 @@ class ProcessesCommand : SlashOnlyCommand {
     override val options = setOf(
         OptionData(OptionType.STRING, "pid", "The ID of the process to terminate")
             .setAutoComplete(true))
-    override val staleInteractionHandling = StaleInteractionHandling.REMOVE_COMPONENTS
+    override val staleComponentHandling = StaleComponentHandling.REMOVE_COMPONENTS
 
     override suspend fun invoke(event: SlashCommandInteractionEvent) {
         val processes = event.jda.processes.takeUnless { it.isEmpty() }

diff --git a/src/main/kotlin/io/ileukocyte/hibernum/commands/general/AboutCommand.kt b/src/main/kotlin/io/ileukocyte/hibernum/commands/general/AboutCommand.kt
@@ -6,7 +6,7 @@ import io.ileukocyte.hibernum.Immutable
 import io.ileukocyte.hibernum.audio.audioPlayer
 import io.ileukocyte.hibernum.builders.buildEmbed
 import io.ileukocyte.hibernum.commands.*
-import io.ileukocyte.hibernum.commands.GenericCommand.StaleInteractionHandling
+import io.ileukocyte.hibernum.commands.GenericCommand.StaleComponentHandling
 import io.ileukocyte.hibernum.extensions.*
 import io.ileukocyte.hibernum.handlers.CommandHandler
 import io.ileukocyte.hibernum.utils.asText
@@ -38,7 +38,7 @@ class AboutCommand : TextCommand {
     override val options = setOf(
         OptionData(OptionType.BOOLEAN, "ephemeral", "Whether the response should be invisible to other users"))
     override val aliases = setOf("bot-info", "info", "stats")
-    override val staleInteractionHandling = StaleInteractionHandling.EXECUTE_COMMAND
+    override val staleComponentHandling = StaleComponentHandling.EXECUTE_COMMAND
 
     override suspend fun invoke(event: MessageReceivedEvent, args: String?) {
         val appInfo = event.jda.retrieveApplicationInfo().await()

diff --git a/src/main/kotlin/io/ileukocyte/hibernum/commands/general/SessionsCommand.kt b/src/main/kotlin/io/ileukocyte/hibernum/commands/general/SessionsCommand.kt
@@ -5,7 +5,7 @@ import com.google.common.collect.Lists
 import io.ileukocyte.hibernum.Immutable
 import io.ileukocyte.hibernum.builders.buildEmbed
 import io.ileukocyte.hibernum.commands.CommandException
-import io.ileukocyte.hibernum.commands.GenericCommand.StaleInteractionHandling
+import io.ileukocyte.hibernum.commands.GenericCommand.StaleComponentHandling
 import io.ileukocyte.hibernum.commands.SlashOnlyCommand
 import io.ileukocyte.hibernum.commands.`fun`.AkinatorCommand
 import io.ileukocyte.hibernum.commands.`fun`.ChomskyCommand
@@ -45,7 +45,7 @@ class SessionsCommand : SlashOnlyCommand {
     override val options = setOf(
         OptionData(STRING, "id", "The ID of the session to abort")
             .setAutoComplete(true))
-    override val staleInteractionHandling = StaleInteractionHandling.REMOVE_COMPONENTS
+    override val staleComponentHandling = StaleComponentHandling.REMOVE_COMPONENTS
     override val neglectProcessBlock = true
 
     override suspend fun invoke(event: SlashCommandInteractionEvent) {

diff --git a/src/main/kotlin/io/ileukocyte/hibernum/commands/music/NowPlayingCommand.kt b/src/main/kotlin/io/ileukocyte/hibernum/commands/music/NowPlayingCommand.kt
@@ -6,7 +6,7 @@ import io.ileukocyte.hibernum.Immutable
 import io.ileukocyte.hibernum.audio.*
 import io.ileukocyte.hibernum.builders.buildEmbed
 import io.ileukocyte.hibernum.commands.CommandException
-import io.ileukocyte.hibernum.commands.GenericCommand.StaleInteractionHandling
+import io.ileukocyte.hibernum.commands.GenericCommand.StaleComponentHandling
 import io.ileukocyte.hibernum.commands.TextCommand
 import io.ileukocyte.hibernum.commands.music.LoopCommand.Companion.getButton
 import io.ileukocyte.hibernum.commands.music.LoopCommand.Companion.getNext
@@ -36,7 +36,7 @@ class NowPlayingCommand : TextCommand {
         OptionData(OptionType.BOOLEAN, "gui-player", "Whether the button player should " +
                 "be added to the bot message (default is true)"))
     override val aliases = setOf("np", "now", "playing", "playing-now")
-    override val staleInteractionHandling = StaleInteractionHandling.REMOVE_COMPONENTS
+    override val staleComponentHandling = StaleComponentHandling.REMOVE_COMPONENTS
 
     override suspend fun invoke(event: MessageReceivedEvent, args: String?) {
         val audioPlayer = event.guild.audioPlayer ?: return

diff --git a/src/main/kotlin/io/ileukocyte/hibernum/commands/music/QueueCommand.kt b/src/main/kotlin/io/ileukocyte/hibernum/commands/music/QueueCommand.kt
@@ -8,7 +8,7 @@ import io.ileukocyte.hibernum.Immutable
 import io.ileukocyte.hibernum.audio.*
 import io.ileukocyte.hibernum.builders.buildEmbed
 import io.ileukocyte.hibernum.commands.CommandException
-import io.ileukocyte.hibernum.commands.GenericCommand.StaleInteractionHandling
+import io.ileukocyte.hibernum.commands.GenericCommand.StaleComponentHandling
 import io.ileukocyte.hibernum.commands.TextCommand
 import io.ileukocyte.hibernum.commands.music.LoopCommand.Companion.getButton
 import io.ileukocyte.hibernum.commands.music.LoopCommand.Companion.getNext
@@ -44,7 +44,7 @@ class QueueCommand : TextCommand {
         OptionData(OptionType.BOOLEAN, "gui-player", "Whether the button player should " +
                 "be added to the queue message (default is true)"),
     )
-    override val staleInteractionHandling = StaleInteractionHandling.REMOVE_COMPONENTS
+    override val staleComponentHandling = StaleComponentHandling.REMOVE_COMPONENTS
 
     override suspend fun invoke(event: MessageReceivedEvent, args: String?) {
         val audioPlayer = event.guild.audioPlayer ?: return

diff --git a/src/main/kotlin/io/ileukocyte/hibernum/commands/utility/DictionaryCommand.kt b/src/main/kotlin/io/ileukocyte/hibernum/commands/utility/DictionaryCommand.kt
@@ -3,7 +3,7 @@ package io.ileukocyte.hibernum.commands.utility
 import io.ileukocyte.hibernum.Immutable
 import io.ileukocyte.hibernum.builders.buildEmbed
 import io.ileukocyte.hibernum.commands.CommandException
-import io.ileukocyte.hibernum.commands.GenericCommand.StaleInteractionHandling
+import io.ileukocyte.hibernum.commands.GenericCommand.StaleComponentHandling
 import io.ileukocyte.hibernum.commands.NoArgumentsException
 import io.ileukocyte.hibernum.commands.TextCommand
 import io.ileukocyte.hibernum.commands.usageGroupOf
@@ -49,7 +49,7 @@ class DictionaryCommand : TextCommand {
         OptionData(OptionType.STRING, "term", "The term to define", true))
     override val usages = setOf(usageGroupOf("term".toClassicTextUsage()))
     override val cooldown = 5L
-    override val staleInteractionHandling = StaleInteractionHandling.REMOVE_COMPONENTS
+    override val staleComponentHandling = StaleComponentHandling.REMOVE_COMPONENTS
 
     private val jsonSerializer = Json { ignoreUnknownKeys = true }
     private val client = Immutable.HTTP_CLIENT.config {

diff --git a/src/main/kotlin/io/ileukocyte/hibernum/handlers/CommandHandler.kt b/src/main/kotlin/io/ileukocyte/hibernum/handlers/CommandHandler.kt
@@ -2,7 +2,7 @@ package io.ileukocyte.hibernum.handlers
 
 import io.ileukocyte.hibernum.Immutable
 import io.ileukocyte.hibernum.commands.*
-import io.ileukocyte.hibernum.commands.GenericCommand.StaleInteractionHandling
+import io.ileukocyte.hibernum.commands.GenericCommand.StaleComponentHandling
 import io.ileukocyte.hibernum.extensions.*
 import io.ileukocyte.hibernum.utils.asText
 import io.ileukocyte.hibernum.utils.getProcessByEntities
@@ -333,8 +333,8 @@ object CommandHandler : MutableSet<GenericCommand> {
             getByInteractionName(event.componentId.split("-").first())?.let { command ->
                 CoroutineScope(CommandContext).launch {
                     if (event.message.timeCreated.isBefore(event.jda.startDate)) {
-                        when (command.staleInteractionHandling) {
-                            StaleInteractionHandling.DELETE_ORIGINAL -> {
+                        when (command.staleComponentHandling) {
+                            StaleComponentHandling.DELETE_ORIGINAL -> {
                                 try {
                                     event.message.delete().queue(null) {}
                                 } catch (_: IllegalStateException) {}
@@ -350,7 +350,7 @@ object CommandHandler : MutableSet<GenericCommand> {
 
                                 return@launch
                             }
-                            StaleInteractionHandling.REMOVE_COMPONENTS -> {
+                            StaleComponentHandling.REMOVE_COMPONENTS -> {
                                 event.message.editMessageComponents().queue(null) {}
 
                                 return@launch
@@ -417,8 +417,8 @@ object CommandHandler : MutableSet<GenericCommand> {
             getByInteractionName(event.componentId.split("-").first())?.let { command ->
                 CoroutineScope(CommandContext).launch {
                     if (event.message.timeCreated.isBefore(event.jda.startDate)) {
-                        when (command.staleInteractionHandling) {
-                            StaleInteractionHandling.DELETE_ORIGINAL -> {
+                        when (command.staleComponentHandling) {
+                            StaleComponentHandling.DELETE_ORIGINAL -> {
                                 try {
                                     event.message.delete().queue(null) {}
                                 } catch (_: IllegalStateException) {}
@@ -434,7 +434,7 @@ object CommandHandler : MutableSet<GenericCommand> {
 
                                 return@launch
                             }
-                            StaleInteractionHandling.REMOVE_COMPONENTS -> {
+                            StaleComponentHandling.REMOVE_COMPONENTS -> {
                                 event.message.editMessageComponents().queue(null) {}
 
                                 return@launch