Rewrite Spring configuration metadata generator (#262)

Author: freya022

BotCommands-core/build.gradle.kts

@@ -9,8 +9,7 @@ plugins {
     id("kotlin-conventions")
     id("publish-conventions")
     id("dokka-conventions")
-
-    alias(libs.plugins.ksp)
+    id("spring-configuration-metadata-conventions")
 }
 
 // Register other source sets
@@ -90,10 +89,6 @@ dependencies {
     compileOnly(libs.jetbrains.annotations)
     api(libs.jspecify)
 
-    // -------------------- ANNOTATION PROCESSORS --------------------
-
-    ksp(projects.springPropertiesProcessor)
-
     // -------------------- DOC EXAMPLES DEPENDENCIES --------------------
 
     // YAML (de)serialization

BotCommands-core/src/main/kotlin/io/github/freya022/botcommands/api/core/config/BAppEmojisConfig.kt

@@ -7,18 +7,24 @@ import io.github.freya022.botcommands.internal.core.config.ConfigurationValue
 
 @InjectedService
 interface BAppEmojisConfig : IConfig, BAppEmojisConfigProps {
+
     override val configType get() = BAppEmojisConfig::class.java
 }
 
 interface BAppEmojisConfigProps {
+
     /**
      * Allows uploading application emojis at startup, and retrieving them from [AppEmojisRegistry].
      *
      * Default: `false`
      *
      * Spring property: `botcommands.app.emojis.enable`
      */
-    @ConfigurationValue(path = "botcommands.app.emojis.enable", defaultValue = "false")
+    @get:ConfigurationValue(
+        path = "botcommands.app.emojis.enable",
+        description = "Allows uploading application emojis at startup, and retrieving them from [AppEmojisRegistry].",
+        defaultValue = "false",
+    )
     val enable: Boolean
 
     /**
@@ -31,12 +37,17 @@ interface BAppEmojisConfigProps {
      *
      * Spring property: `botcommands.app.emojis.deleteOnOutOfSlots`
      */
-    @ConfigurationValue(path = "botcommands.app.emojis.deleteOnOutOfSlots", defaultValue = "false")
+    @get:ConfigurationValue(
+        path = "botcommands.app.emojis.deleteOnOutOfSlots",
+        description = "Allows deleting application emojis that are not managed by this application, starting from the oldest. This keeps emojis by name, not by content.",
+        defaultValue = "false",
+    )
     val deleteOnOutOfSlots: Boolean
 }
 
 @ConfigDSL
 class BAppEmojisConfigBuilder internal constructor() : BAppEmojisConfigProps {
+
     @set:JvmName("enable")
     override var enable: Boolean = false
 

BotCommands-core/src/main/kotlin/io/github/freya022/botcommands/api/core/config/BApplicationConfig.kt

@@ -30,12 +30,14 @@ import kotlin.io.path.Path
 
 @InjectedService
 interface BApplicationConfig : IConfig, BApplicationConfigProps {
+
     override val configType get() = BApplicationConfig::class.java
 }
 
 interface BApplicationConfigProps {
+
     /**
-     * Whether application commands should be listened for.
+     * Whether the application commands feature should be enabled.
      *
      * You can use [@RequiresApplicationCommands][RequiresApplicationCommands]
      * to disable services when this is set to `false`.
@@ -44,7 +46,11 @@ interface BApplicationConfigProps {
      *
      * Spring property: `botcommands.application.enable`
      */
-    @ConfigurationValue(path = "botcommands.application.enable", defaultValue = "true")
+    @get:ConfigurationValue(
+        path = "botcommands.application.enable",
+        description = "Whether the application commands feature should be enabled.",
+        defaultValue = "true",
+    )
     val enable: Boolean
 
     /**
@@ -54,17 +60,23 @@ interface BApplicationConfigProps {
      *
      * Spring property: `botcommands.application.guildsToUpdate`
      */
-    @ConfigurationValue(path = "botcommands.application.guildsToUpdate")
+    @get:ConfigurationValue(
+        path = "botcommands.application.guildsToUpdate",
+        description = "If not empty, application commands will only be updated in these guilds. Existing commands won't be removed in other guilds, global commands will still be updated.",
+    )
     val guildsToUpdate: List<Long>
 
     /**
-     * Test guilds IDs for all commands annotated with [Test]
+     * Test guilds IDs for all commands annotated with [Test].
      *
      * Spring property: `botcommands.application.testGuildIds`
      *
      * @see Test @Test
      */
-    @ConfigurationValue(path = "botcommands.application.testGuildIds")
+    @get:ConfigurationValue(
+        path = "botcommands.application.testGuildIds",
+        description = "Test guilds IDs for all commands annotated with [Test].",
+    )
     val testGuildIds: List<Long>
 
     /**
@@ -76,7 +88,11 @@ interface BApplicationConfigProps {
      *
      * Spring property: `botcommands.application.disableAutocompleteCache`
      */
-    @ConfigurationValue(path = "botcommands.application.disableAutocompleteCache", defaultValue = "false")
+    @get:ConfigurationValue(
+        path = "botcommands.application.disableAutocompleteCache",
+        description = "Disables autocomplete caching, unless [CacheAutocomplete.forceCache] is set to `true`.",
+        defaultValue = "false",
+    )
     val disableAutocompleteCache: Boolean
 
     /**
@@ -102,7 +118,11 @@ interface BApplicationConfigProps {
      *
      * Spring property: `botcommands.application.forceGuildCommands`
      */
-    @ConfigurationValue(path = "botcommands.application.forceGuildCommands", defaultValue = "false")
+    @get:ConfigurationValue(
+        path = "botcommands.application.forceGuildCommands",
+        description = "Whether all application commands should be registered on each guild, regardless of the command scope on the annotation.",
+        defaultValue = "false",
+    )
     val forceGuildCommands: Boolean
 
     /**
@@ -129,7 +149,10 @@ interface BApplicationConfigProps {
      * @see DefaultLocalizationMapProvider
      * @see JacksonLocalizationMapReader
      */
-    @ConfigurationValue(path = "botcommands.application.localizations")
+    @get:ConfigurationValue(
+        path = "botcommands.application.localizations",
+        description = "Map where the key is the base bundle name, and the values are the supported locales, see the docs of [BApplicationConfigBuilder#addLocalization].",
+    )
     val baseNameToLocalesMap: Map<String, List<DiscordLocale>>
 
     /**
@@ -143,16 +166,22 @@ interface BApplicationConfigProps {
      *
      * Spring property: `botcommands.application.logMissingLocalizationKeys`
      */
-    @ConfigurationValue(path = "botcommands.application.logMissingLocalizationKeys", defaultValue = "false")
+    @get:ConfigurationValue(
+        path = "botcommands.application.logMissingLocalizationKeys",
+        description = "Whether to log a `WARN` if a localization key isn't found when registering the commands.",
+        defaultValue = "false",
+    )
     val logMissingLocalizationKeys: Boolean
 }
 
 @ConfigDSL
 class BApplicationConfigBuilder internal constructor() : BApplicationConfigProps {
+
     @set:JvmName("enable")
     override var enable: Boolean = true
     override val guildsToUpdate: MutableList<Long> = mutableListOf()
     override val testGuildIds: MutableList<Long> = mutableListOf()
+
     @set:DevConfig
     @set:JvmName("disableAutocompleteCache")
     override var disableAutocompleteCache = false

BotCommands-core/src/main/kotlin/io/github/freya022/botcommands/api/core/config/BComponentsConfig.kt

@@ -1,37 +1,46 @@
 package io.github.freya022.botcommands.api.core.config
 
 import io.github.freya022.botcommands.api.components.Buttons
-import io.github.freya022.botcommands.api.components.Components
 import io.github.freya022.botcommands.api.components.SelectMenus
+import io.github.freya022.botcommands.api.components.annotations.RequiresComponents
 import io.github.freya022.botcommands.api.core.db.ConnectionSupplier
 import io.github.freya022.botcommands.api.core.service.annotations.InjectedService
 import io.github.freya022.botcommands.internal.core.config.ConfigDSL
 import io.github.freya022.botcommands.internal.core.config.ConfigurationValue
 
 @InjectedService
 interface BComponentsConfig : IConfig, BComponentsConfigProps {
+
     override val configType get() = BComponentsConfig::class.java
 }
 
 interface BComponentsConfigProps {
+
     /**
-     * Allows loading component services,
-     * such as [Components], [Buttons] and [SelectMenus].
+     * Whether the components feature should be enabled. Enabling this requires a [ConnectionSupplier] service.
      *
-     * This requires a [ConnectionSupplier] service to be present
+     * You can use [@RequiresComponents][RequiresComponents]
+     * to disable services when this is set to `false`.
      *
      * Default: `false`
      *
      * Spring property: `botcommands.components.enable` ; Spring property takes over this config property.
      *
      * @see ConnectionSupplier
+     * @see Buttons
+     * @see SelectMenus
      */
-    @ConfigurationValue(path = "botcommands.components.enable", defaultValue = "false")
+    @get:ConfigurationValue(
+        path = "botcommands.components.enable",
+        description = "Whether the components feature should be enabled. Enabling this requires a [ConnectionSupplier] service.",
+        defaultValue = "false",
+    )
     val enable: Boolean
 }
 
 @ConfigDSL
 class BComponentsConfigBuilder internal constructor() : BComponentsConfigProps {
+
     @set:JvmName("enable")
     override var enable: Boolean = false
 

BotCommands-core/src/main/kotlin/io/github/freya022/botcommands/api/core/config/BConfig.kt

@@ -22,6 +22,7 @@ import kotlin.reflect.KClass
 
 @InjectedService
 interface BConfig : IConfig, BConfigProps {
+
     override val configType get() = BConfig::class.java
 
     val eventManagerConfig: BEventManagerConfig
@@ -49,6 +50,7 @@ interface BConfig : IConfig, BConfigProps {
 }
 
 interface BConfigProps {
+
     /**
      * Predefined user IDs of the bot owners, allowing bypassing cooldowns, user permission checks,
      * and having [hidden commands][Hidden] shown.
@@ -59,32 +61,47 @@ interface BConfigProps {
      *
      * Spring property: `botcommands.core.predefinedOwnerIds`
      */
-    @ConfigurationValue(path = "botcommands.core.predefinedOwnerIds")
+    @get:ConfigurationValue(
+        path = "botcommands.core.predefinedOwnerIds",
+        description = "Predefined user IDs of the bot owners, allowing bypassing cooldowns, user permission checks, and having [Hidden] commands shown. See the documentation for more details.",
+    )
     val predefinedOwnerIds: Set<Long>
 
     /**
      * The packages the framework will scan through for services, commands, handlers...
      *
      * Spring property: `botcommands.core.packages`
      */
-    @ConfigurationValue(path = "botcommands.core.packages")
+    @get:ConfigurationValue(
+        path = "botcommands.core.packages",
+        description = "The packages the framework will scan through for services, commands, handlers...",
+    )
     val packages: Set<String>
+
     /**
      * Additional classes the framework will scan through for services, commands, handlers...
      *
      * Spring property: `botcommands.core.classes`
      */
-    @ConfigurationValue(path = "botcommands.core.classes", type = "java.util.Set<java.lang.Class<?>>")
+    @get:ConfigurationValue(
+        path = "botcommands.core.classes",
+        description = "Additional classes the framework will scan through for services, commands, handlers...",
+        type = "java.util.Set<java.lang.Class<?>>",
+    )
     val classes: Set<Class<*>>
 
     /**
-     * Disables sending exceptions to the bot owners
+     * Disables sending exceptions to the bot owners.
      *
      * Default: `false`
      *
      * Spring property: `botcommands.core.disableExceptionsInDMs`
      */
-    @ConfigurationValue(path = "botcommands.core.disableExceptionsInDMs", defaultValue = "false")
+    @get:ConfigurationValue(
+        path = "botcommands.core.disableExceptionsInDMs",
+        description = "Disables sending exceptions to the bot owners.",
+        defaultValue = "false",
+    )
     val disableExceptionsInDMs: Boolean
 
     /**
@@ -96,17 +113,24 @@ interface BConfigProps {
      *
      * @see BotOwners
      */
-    @ConfigurationValue(path = "botcommands.core.enableOwnerBypass", defaultValue = "false")
+    @get:ConfigurationValue(
+        path = "botcommands.core.enableOwnerBypass",
+        description = "Enables *bot* owners to bypass certain limits.",
+        defaultValue = "false",
+    )
     val enableOwnerBypass: Boolean
 
     /**
-     * Gateway intents to ignore when checking for [event listeners][BEventListener] intents.
+     * Gateway intents to ignore when checking for required intents of [event listeners][BEventListener].
      *
      * Spring property: `botcommands.core.ignoredIntents`
      *
      * @see BEventListener.ignoreIntents
      */
-    @ConfigurationValue(path = "botcommands.core.ignoredIntents")
+    @get:ConfigurationValue(
+        path = "botcommands.core.ignoredIntents",
+        description = "Gateway intents to ignore when checking for required intents of event listeners.",
+    )
     val ignoredIntents: Set<GatewayIntent>
 
     /**
@@ -118,7 +142,11 @@ interface BConfigProps {
      *
      * @see PriorityGlobalRestRateLimiter
      */
-    @ConfigurationValue("botcommands.core.ignoreRestRateLimiter", defaultValue = "false")
+    @get:ConfigurationValue(
+        path = "botcommands.core.ignoreRestRateLimiter",
+        description = "Suppresses warnings about the default [RestRateLimiter] being used for large bots.",
+        defaultValue = "false",
+    )
     val ignoreRestRateLimiter: Boolean
 
     val classGraphProcessors: List<ClassGraphProcessor>
@@ -132,7 +160,11 @@ interface BConfigProps {
      *
      * Spring property: `botcommands.core.enableShutdownHook`
      */
-    @ConfigurationValue("botcommands.core.enableShutdownHook", defaultValue = "true")
+    @get:ConfigurationValue(
+        path = "botcommands.core.enableShutdownHook",
+        description = "Whether to use a shutdown hook to call [BContext.shutdownNow] when the JVM is exiting **gracefully**.",
+        defaultValue = "true",
+    )
     val enableShutdownHook: Boolean
 }
 
@@ -152,13 +184,15 @@ inline fun <reified T : IConfig> BConfig.getConfigOrNull(): T? = getConfigOrNull
 
 @ConfigDSL
 class BConfigBuilder : BConfigProps {
+
     override val packages: MutableSet<String> = HashSet()
     override val classes: MutableSet<Class<*>> = HashSet()
 
     override val predefinedOwnerIds: MutableSet<Long> = HashSet()
 
     @set:JvmName("disableExceptionsInDMs")
     override var disableExceptionsInDMs = false
+
     @set:JvmName("enableOwnerBypass")
     override var enableOwnerBypass = false