docs: more docs

Author: twisti-dev

.idea/php.xml

@@ -3,19 +3,40 @@ package dev.slne.surf.surfapi.core.api.command
 import dev.slne.surf.surfapi.core.api.command.builder.CommandExceptionBuilder
 import dev.slne.surf.surfapi.core.api.command.exception.WrapperCommandExceptionComponent
 import net.kyori.adventure.text.ComponentLike
-import org.jetbrains.annotations.ApiStatus
 
-@ApiStatus.NonExtendable
+/**
+ * Utility object for command-related operations and error handling in the Surf API.
+ * Provides methods to create and throw custom command exceptions with user-friendly error messages.
+ */
 object SurfCommandUtil {
+
+    /**
+     * Creates a custom exception with the given message.
+     *
+     * @param message The message to include in the exception, as a [ComponentLike].
+     * @return An instance of [WrapperCommandExceptionComponent].
+     */
     @JvmStatic
     fun createException(message: ComponentLike) =
         WrapperCommandExceptionComponent(message.asComponent())
 
+    /**
+     * Throws a custom command exception with the given message.
+     *
+     * @param message The message to include in the exception, as a [ComponentLike].
+     * @throws WrapperCommandExceptionComponent Always throws the created exception.
+     */
     @JvmStatic
     fun failWithMessage(message: ComponentLike) {
         throw createException(message)
     }
 
+    /**
+     * Throws a custom command exception using a provided [CommandExceptionBuilder].
+     *
+     * @param builder The builder used to construct the exception message.
+     * @throws WrapperCommandExceptionComponent Always throws the created exception.
+     */
     @JvmStatic
     fun failWithBuilder(builder: CommandExceptionBuilder) {
         throw createException(builder.build())

surf-api-core/surf-api-core-api/src/main/kotlin/dev/slne/surf/surfapi/core/api/command/SurfCommandUtil.kt

@@ -7,6 +7,12 @@ import dev.slne.surf.surfapi.core.api.messages.ComponentMessage
 import net.kyori.adventure.text.Component
 import java.io.Serial
 
+/**
+ * A wrapper for [CommandSyntaxException] to integrate custom error messages
+ * as [Component] objects within the Surf API.
+ *
+ * @param errorMessage The error message to associate with the exception.
+ */
 class WrapperCommandExceptionComponent(errorMessage: Component) : WrapperCommandSyntaxException(
     CommandSyntaxException(
         SimpleCommandExceptionType(

surf-api-core/surf-api-core-api/src/main/kotlin/dev/slne/surf/surfapi/core/api/command/exception/WrapperCommandExceptionComponent.kt

@@ -5,66 +5,180 @@ import dev.slne.surf.surfapi.core.api.config.manager.SpongeConfigManager
 import dev.slne.surf.surfapi.core.api.util.requiredService
 import java.nio.file.Path
 
+/**
+ * API for managing configuration files in the Surf API, supporting both Sponge and DazzlConf configurations.
+ * Provides methods to create, retrieve, and reload configuration files in various formats (YAML, JSON).
+ */
 interface SurfConfigApi {
 
+    /**
+     * Creates a DazzlConf configuration file.
+     *
+     * @param C The type of the configuration class.
+     * @param configClass The class of the configuration.
+     * @param configFolder The folder where the configuration file is stored.
+     * @param configFileName The name of the configuration file. Must follow the YAML file name pattern.
+     * @return An instance of the configuration class [C].
+     */
     @PreferUsingSpongeConfigOverDazzlConf
     fun <C> createDazzlConfig(
         configClass: Class<C>,
         configFolder: Path,
-        configFileName: @YamlConfigFileNamePattern String
+        configFileName: @YamlConfigFileNamePattern String,
     ): C
 
+    /**
+     * Retrieves a DazzlConf configuration.
+     *
+     * @param C The type of the configuration class.
+     * @param configClass The class of the configuration.
+     * @return An instance of the configuration class [C].
+     */
     @PreferUsingSpongeConfigOverDazzlConf
     fun <C> getDazzlConfig(configClass: Class<C>): C
 
+    /**
+     * Reloads a DazzlConf configuration from the file.
+     *
+     * @param C The type of the configuration class.
+     * @param configClass The class of the configuration.
+     * @return The reloaded instance of the configuration class [C].
+     */
     @PreferUsingSpongeConfigOverDazzlConf
     fun <C> reloadDazzlConfig(configClass: Class<C>): C
 
+    /**
+     * Creates a Sponge YAML configuration file.
+     *
+     * @param C The type of the configuration class.
+     * @param configClass The class of the configuration.
+     * @param configFolder The folder where the configuration file is stored.
+     * @param configFileName The name of the configuration file. Must follow the YAML file name pattern.
+     * @return An instance of the configuration class [C].
+     */
     fun <C> createSpongeYmlConfig(
         configClass: Class<C>,
         configFolder: Path,
-        configFileName: @YamlConfigFileNamePattern String
+        configFileName: @YamlConfigFileNamePattern String,
     ): C
 
+    /**
+     * Creates a Sponge JSON configuration file.
+     *
+     * @param C The type of the configuration class.
+     * @param configClass The class of the configuration.
+     * @param configFolder The folder where the configuration file is stored.
+     * @param configFileName The name of the configuration file. Must follow the JSON file name pattern.
+     * @return An instance of the configuration class [C].
+     */
     fun <C> createSpongeJsonConfig(
         configClass: Class<C>,
         configFolder: Path,
-        configFileName: @JsonConfigFileNamePattern String
+        configFileName: @JsonConfigFileNamePattern String,
     ): C
 
+    /**
+     * Retrieves a Sponge configuration.
+     *
+     * @param C The type of the configuration class.
+     * @param configClass The class of the configuration.
+     * @return An instance of the configuration class [C].
+     */
     fun <C> getSpongeConfig(configClass: Class<C>): C
 
+    /**
+     * Reloads a Sponge configuration from the file.
+     *
+     * @param C The type of the configuration class.
+     * @param configClass The class of the configuration.
+     * @return The reloaded instance of the configuration class [C].
+     */
     fun <C> reloadSpongeConfig(configClass: Class<C>): C
 
+    /**
+     * Retrieves the [SpongeConfigManager] for a specific configuration class.
+     *
+     * @param C The type of the configuration class.
+     * @param configClass The class of the configuration.
+     * @return An instance of [SpongeConfigManager] for the configuration class [C].
+     */
     fun <C> getSpongeConfigManagerForConfig(configClass: Class<C>): SpongeConfigManager<C>
 
     companion object {
+        /**
+         * Retrieves the singleton instance of [SurfConfigApi].
+         */
         val instance = requiredService<SurfConfigApi>()
     }
 }
 
+/**
+ * Retrieves the singleton instance of [SurfConfigApi].
+ */
 val surfConfigApi get() = SurfConfigApi.instance
 
+/**
+ * Creates a DazzlConf configuration using a reified type.
+ *
+ * @param C The type of the configuration class.
+ * @param configFolder The folder where the configuration file is stored.
+ * @param configFileName The name of the configuration file. Must follow the YAML file name pattern.
+ * @return An instance of the configuration class [C].
+ */
 @PreferUsingSpongeConfigOverDazzlConf
 inline fun <reified C> SurfConfigApi.createDazzlConfig(
     configFolder: Path,
-    configFileName: @YamlConfigFileNamePattern String
+    configFileName: @YamlConfigFileNamePattern String,
 ) = createDazzlConfig(C::class.java, configFolder, configFileName)
 
+/**
+ * Retrieves a DazzlConf configuration using a reified type.
+ *
+ * @param C The type of the configuration class.
+ * @return An instance of the configuration class [C].
+ */
 @PreferUsingSpongeConfigOverDazzlConf
 inline fun <reified C> SurfConfigApi.getDazzlConfig() = getDazzlConfig(C::class.java)
 
+/**
+ * Reloads a DazzlConf configuration using a reified type.
+ *
+ * @param C The type of the configuration class.
+ * @return The reloaded instance of the configuration class [C].
+ */
 @PreferUsingSpongeConfigOverDazzlConf
 inline fun <reified C> SurfConfigApi.reloadDazzlConfig() = reloadDazzlConfig(C::class.java)
 
+/**
+ * Creates a Sponge YAML configuration using a reified type.
+ *
+ * @param C The type of the configuration class.
+ * @param configFolder The folder where the configuration file is stored.
+ * @param configFileName The name of the configuration file. Must follow the YAML file name pattern.
+ * @return An instance of the configuration class [C].
+ */
 inline fun <reified C> SurfConfigApi.createSpongeYmlConfig(
     configFolder: Path,
-    configFileName: @YamlConfigFileNamePattern String
+    configFileName: @YamlConfigFileNamePattern String,
 ) = createSpongeYmlConfig(C::class.java, configFolder, configFileName)
 
+/**
+ * Creates a Sponge JSON configuration using a reified type.
+ *
+ * @param C The type of the configuration class.
+ * @param configFolder The folder where the configuration file is stored.
+ * @param configFileName The name of the configuration file. Must follow the JSON file name pattern.
+ * @return An instance of the configuration class [C].
+ */
 inline fun <reified C> SurfConfigApi.createSpongeJsonConfig(
     configFolder: Path,
-    configFileName: @JsonConfigFileNamePattern String
+    configFileName: @JsonConfigFileNamePattern String,
 ) = createSpongeJsonConfig(C::class.java, configFolder, configFileName)
 
+/**
+ * Retrieves a Sponge configuration using a reified type.
+ *
+ * @param C The type of the configuration class.
+ * @return An instance of the configuration class [C].
+ */
 inline fun <reified C> SurfConfigApi.getSpongeConfig() = getSpongeConfig(C::class.java)

surf-api-core/surf-api-core-api/src/main/kotlin/dev/slne/surf/surfapi/core/api/config/SurfConfigApi.kt

@@ -9,12 +9,20 @@ private const val YAML_CONFIG_FILE_NAME_PATTERN = "^[a-zA-Z0-9_-]+\\.(yml|yaml)$
 @Language("RegExp")
 private const val JSON_CONFIG_FILE_NAME_PATTERN = "^[a-zA-Z0-9_-]+\\.(json)$"
 
+/**
+ * Annotation to specify that a file name must follow a YAML configuration file name pattern.
+ * The file name must match the regular expression: `^[a-zA-Z0-9_-]+\\.(yml|yaml)$`.
+ */
 @Pattern(YAML_CONFIG_FILE_NAME_PATTERN)
 @Retention(AnnotationRetention.RUNTIME)
 @Target(AnnotationTarget.CLASS, AnnotationTarget.TYPE, AnnotationTarget.TYPE_PARAMETER)
 @MustBeDocumented
 annotation class YamlConfigFileNamePattern
 
+/**
+ * Annotation to specify that a file name must follow a JSON configuration file name pattern.
+ * The file name must match the regular expression: `^[a-zA-Z0-9_-]+\\.(json)$`.
+ */
 @Pattern(JSON_CONFIG_FILE_NAME_PATTERN)
 @Retention(AnnotationRetention.RUNTIME)
 @Target(AnnotationTarget.CLASS, AnnotationTarget.TYPE, AnnotationTarget.TYPE_PARAMETER)

surf-api-core/surf-api-core-api/src/main/kotlin/dev/slne/surf/surfapi/core/api/config/common.kt

@@ -23,12 +23,26 @@ import java.util.concurrent.TimeUnit
 @Target(AnnotationTarget.CLASS, AnnotationTarget.FUNCTION)
 annotation class PreferUsingSpongeConfigOverDazzlConf
 
+/**
+ * Manages configurations using the DazzlConf library, including loading, saving, and reloading configurations.
+ * Provides resilience against syntax or invalid data errors and defaults to a valid configuration when such errors occur.
+ *
+ * @param C The type of the configuration class.
+ * @property config The current configuration instance, or `null` if not yet loaded.
+ */
 @PreferUsingSpongeConfigOverDazzlConf
 class DazzlConfConfigManager<C> private constructor(private val helper: ConfigurationHelper<C>) {
     @Volatile
     var config: C? = null
         private set
 
+    /**
+     * Reloads the configuration from the file.
+     * If a syntax or validation error occurs, a default configuration is used.
+     *
+     * @return The reloaded configuration instance.
+     * @throws RuntimeException if an I/O error or other critical issue occurs.
+     */
     fun reloadConfig(): C {
         try {
             config = helper.reloadConfigData()
@@ -65,6 +79,11 @@ class DazzlConfConfigManager<C> private constructor(private val helper: Configur
         return config ?: error("Config is null after reload")
     }
 
+    /**
+     * Retrieves the current configuration, reloading it if not already loaded.
+     *
+     * @return The configuration instance.
+     */
     fun getOrCreateConfig(): C {
         val config = config ?: reloadConfig()
         return config
@@ -73,6 +92,15 @@ class DazzlConfConfigManager<C> private constructor(private val helper: Configur
     companion object {
         private val log = logger()
 
+        /**
+         * Creates a new instance of [DazzlConfConfigManager] for managing a YAML configuration.
+         *
+         * @param C The type of the configuration class.
+         * @param configClass The class of the configuration.
+         * @param configFolder The folder where the configuration file is stored.
+         * @param configFileName The name of the configuration file. Must match the YAML file name pattern.
+         * @return A new instance of [DazzlConfConfigManager].
+         */
         @JvmStatic
         fun <C> create(
             configClass: Class<C>,