Merge pull request #23 from SLNE-Development/feat/docs

Feat/docs

Author: twisti-dev

.idea/php.xml

@@ -16,12 +16,22 @@ interface SurfCoreApi {
      */
     fun sendPlayerToServer(playerUuid: UUID, server: String)
 
+    /**
+     * Returns the platform-specific player object for the specified player.
+     */
     fun getPlayer(playerUuid: UUID): Any?
 
     companion object {
+
+        /**
+         * The instance of the SurfCoreApi.
+         */
         @JvmStatic
         val instance = requiredService<SurfCoreApi>()
     }
 }
 
+/**
+ * The instance of the SurfCoreApi.
+ */
 val surfCoreApi get() = SurfCoreApi.instance

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

@@ -3,29 +3,127 @@ package dev.slne.surf.surfapi.core.api.collection
 import it.unimi.dsi.fastutil.objects.ObjectIterator
 import it.unimi.dsi.fastutil.objects.ObjectSet
 
+/**
+ * A specialized implementation of [ObjectSet] that transforms elements between two types, `O` and `M`, using
+ * the provided transformation functions. This enables a dynamic view of a set where elements are transformed
+ * on-the-fly during iteration or when performing operations.
+ *
+ * @param O The type of the elements in the underlying set.
+ * @param M The type of the transformed elements in this set.
+ * @property fromSet The underlying set containing elements of type `O`.
+ * @property toTransformer A function that transforms elements of type `O` to type `M`. Can return null to filter out elements.
+ * @property fromTransformer A function that transforms elements of type `M` to type `O`. Can return null to filter out elements.
+ */
 class TransformingObjectSet<O, M>(
     private val fromSet: ObjectSet<O>,
     private val toTransformer: (O) -> M?,
     private val fromTransformer: (M) -> O?,
 ) : ObjectSet<M> {
+
+    /**
+     * Returns an iterator that transforms elements from the underlying set during iteration.
+     *
+     * @return An iterator over the transformed elements of type `M`.
+     */
     override fun iterator() = object : ObjectIterator<M> {
         private val iterator = fromSet.iterator()
         override fun remove() = iterator.remove()
         override fun next(): M? = toTransformer(iterator.next())
         override fun hasNext() = iterator.hasNext()
     }
 
+    /**
+     * Adds a transformed element to the underlying set.
+     *
+     * @param element The element of type `M` to add.
+     * @return `true` if the underlying set was modified, `false` otherwise.
+     */
     override fun add(element: M?) = fromSet.add(transformFrom(element))
+
+    /**
+     * Removes a transformed element from the underlying set.
+     *
+     * @param element The element of type `M` to remove.
+     * @return `true` if the element was removed, `false` otherwise.
+     */
     override fun remove(element: M) = fromSet.remove(transformFrom(element))
-    override fun addAll(elements: Collection<M?>) = fromSet.addAll(elements.mapNotNull(::transformFrom))
-    override fun removeAll(elements: Collection<M?>) = fromSet.removeAll(elements.mapNotNull(::transformFrom))
-    override fun retainAll(elements: Collection<M?>) = fromSet.retainAll(elements.mapNotNull(::transformFrom))
+
+    /**
+     * Adds all transformed elements from the given collection to the underlying set.
+     *
+     * @param elements A collection of elements of type `M`.
+     * @return `true` if the underlying set was modified, `false` otherwise.
+     */
+    override fun addAll(elements: Collection<M?>) =
+        fromSet.addAll(elements.mapNotNull(::transformFrom))
+
+    /**
+     * Removes all transformed elements in the given collection from the underlying set.
+     *
+     * @param elements A collection of elements of type `M`.
+     * @return `true` if the underlying set was modified, `false` otherwise.
+     */
+    override fun removeAll(elements: Collection<M?>) =
+        fromSet.removeAll(elements.mapNotNull(::transformFrom))
+
+    /**
+     * Retains only the transformed elements in the given collection in the underlying set.
+     *
+     * @param elements A collection of elements of type `M`.
+     * @return `true` if the underlying set was modified, `false` otherwise.
+     */
+    override fun retainAll(elements: Collection<M?>) =
+        fromSet.retainAll(elements.mapNotNull(::transformFrom))
+
+    /**
+     * Removes all elements from the underlying set.
+     */
     override fun clear() = fromSet.clear()
+
+    /**
+     * Returns the number of elements in the transformed set.
+     *
+     * @return The size of the underlying set.
+     */
     override val size: Int get() = fromSet.size
+
+    /**
+     * Checks if the transformed set is empty.
+     *
+     * @return `true` if the underlying set is empty, `false` otherwise.
+     */
     override fun isEmpty() = fromSet.isEmpty()
+
+    /**
+     * Checks if the transformed set contains the specified element.
+     *
+     * @param element The element of type `M` to check.
+     * @return `true` if the element is in the transformed set, `false` otherwise.
+     */
     override fun contains(element: M?) = fromSet.contains(transformFrom(element))
-    override fun containsAll(elements: Collection<M?>) = fromSet.containsAll(elements.mapNotNull(::transformFrom))
 
+    /**
+     * Checks if the transformed set contains all elements in the specified collection.
+     *
+     * @param elements A collection of elements of type `M`.
+     * @return `true` if all elements are in the transformed set, `false` otherwise.
+     */
+    override fun containsAll(elements: Collection<M?>) =
+        fromSet.containsAll(elements.mapNotNull(::transformFrom))
+
+    /**
+     * Transforms an element of type `M` to type `O` using the provided [fromTransformer].
+     *
+     * @param element The element of type `M`.
+     * @return The transformed element of type `O`, or `null` if the transformation is not possible.
+     */
     private fun transformFrom(element: M?) = if (element != null) fromTransformer(element) else null
+
+    /**
+     * Transforms an element of type `O` to type `M` using the provided [toTransformer].
+     *
+     * @param element The element of type `O`.
+     * @return The transformed element of type `M`, or `null` if the transformation is not possible.
+     */
     private fun transformTo(element: O?) = if (element != null) toTransformer(element) else null
-}
+}

surf-api-core/surf-api-core-api/src/main/kotlin/dev/slne/surf/surfapi/core/api/collection/TransformingObjectSet.kt

@@ -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(