more ktdoc cleanup

emyfops · emyfops · commit 6f09bfc58421 · 2025-11-10T17:51:35.000-05:00
diff --git a/src/main/kotlin/com/lambda/module/ModuleRegistry.kt b/src/main/kotlin/com/lambda/module/ModuleRegistry.kt
@@ -20,9 +20,6 @@ package com.lambda.module
 import com.lambda.core.Loadable
 import com.lambda.util.reflections.getInstances
 
-/**
- * The [ModuleRegistry] object is responsible for managing all [Module] instances in the system.
- */
 object ModuleRegistry : Loadable {
     override val priority = 1
 
diff --git a/src/main/kotlin/com/lambda/network/CapeManager.kt b/src/main/kotlin/com/lambda/network/CapeManager.kt
@@ -53,15 +53,13 @@ import kotlin.time.Duration.Companion.seconds
 
 @Suppress("JavaIoSerializableObjectMustHaveReadResolve")
 object CapeManager : ConcurrentHashMap<UUID, String>(), Loadable {
-    // We want to cache images to reduce class B requests
     private val images = capes.walk()
         .filter { it.extension == "png" }
         .associate { it.nameWithoutExtension to NativeImageBackedTexture({ it.nameWithoutExtension }, read(it.inputStream())) }
         .onEach { (key, value) -> mc.textureManager.registerTexture(key.asIdentifier, value) }
 
     private val fetchQueue = mutableListOf<UUID>()
 
-    // We want to cache the cape list to reduce class B requests
     val capeList = runBlocking {
         capes.resolveFile("capes.txt")
             .isOlderThan(24.hours) {
diff --git a/src/main/kotlin/com/lambda/network/api/v1/endpoints/GetCape.kt b/src/main/kotlin/com/lambda/network/api/v1/endpoints/GetCape.kt
@@ -30,8 +30,6 @@ import java.util.*
  *
  * Example:
  *  - id: ab24f5d6-dcf1-45e4-897e-b50a7c5e7422
- *
- * @return results of cape
  */
 suspend fun getCape(uuid: UUID) = runCatching {
     LambdaHttp.get("$apiUrl/api/$apiVersion/cape?id=$uuid").body<Cape>()
diff --git a/src/main/kotlin/com/lambda/network/api/v1/endpoints/GetCapes.kt b/src/main/kotlin/com/lambda/network/api/v1/endpoints/GetCapes.kt
@@ -33,8 +33,6 @@ import java.util.*
  *  - id: ab24f5d6-dcf1-45e4-897e-b50a7c5e7422
  *  - id: 4f332cd7-cf93-427e-a282-53f45f6bb113
  *  - id: fdee323e-7f0c-4c15-8d1c-0f277442342a
- *
- * @return results of capes
  */
 suspend fun getCapes(vararg uuid: UUID) = getCapes(uuid.toList())
 
@@ -45,8 +43,6 @@ suspend fun getCapes(vararg uuid: UUID) = getCapes(uuid.toList())
  *  - id: ab24f5d6-dcf1-45e4-897e-b50a7c5e7422
  *  - id: 4f332cd7-cf93-427e-a282-53f45f6bb113
  *  - id: fdee323e-7f0c-4c15-8d1c-0f277442342a
- *
- * @return results of capes
  */
 suspend fun getCapes(uuids: List<UUID>) = runCatching {
     LambdaHttp.get("$apiUrl/api/$apiVersion/capes") {
diff --git a/src/main/kotlin/com/lambda/network/api/v1/endpoints/LinkDiscord.kt b/src/main/kotlin/com/lambda/network/api/v1/endpoints/LinkDiscord.kt
@@ -31,8 +31,6 @@ import io.ktor.http.*
  *
  * Example:
  *  - token: OTk1MTU1NzcyMzYxMTQ2NDM4
- *
- * @return result of [Authentication]
  */
 suspend fun linkDiscord(discordToken: String) = runCatching {
     LambdaHttp.post("${apiUrl}/api/$apiVersion/link/discord") {
diff --git a/src/main/kotlin/com/lambda/network/api/v1/endpoints/Login.kt b/src/main/kotlin/com/lambda/network/api/v1/endpoints/Login.kt
@@ -31,8 +31,6 @@ import io.ktor.http.*
  * Example:
  *  - username: Notch
  *  - hash: 069a79f444e94726a5befca90e38aaf5
- *
- * @return result of [Authentication]
  */
 suspend fun login(username: String, hash: String) = runCatching {
     LambdaHttp.post("${apiUrl}/api/$apiVersion/login") {
diff --git a/src/main/kotlin/com/lambda/network/api/v1/endpoints/SetCape.kt b/src/main/kotlin/com/lambda/network/api/v1/endpoints/SetCape.kt
@@ -29,8 +29,6 @@ import io.ktor.http.*
  *
  * Example:
  *  - id: galaxy
- *
- * @return nothing
  */
 suspend fun setCape(id: String) = runCatching {
     val resp = LambdaHttp.put("$apiUrl/api/$apiVersion/cape?id=$id") {
diff --git a/src/main/kotlin/com/lambda/network/api/v1/models/Authentication.kt b/src/main/kotlin/com/lambda/network/api/v1/models/Authentication.kt
@@ -20,18 +20,12 @@ package com.lambda.network.api.v1.models
 import com.google.gson.annotations.SerializedName
 
 data class Authentication(
-    // The access token to use for the API
-    // example: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c
     @SerializedName("access_token")
     val accessToken: String,
 
-    // The duration of the token (in seconds).
-    // example: 3600
     @SerializedName("expires_in")
     val expiresIn: Long,
 
-    // The type of the token.
-    // example: Bearer
     @SerializedName("token_type")
     val tokenType: String,
 ) {
diff --git a/src/main/kotlin/com/lambda/network/api/v1/models/Player.kt b/src/main/kotlin/com/lambda/network/api/v1/models/Player.kt
@@ -21,18 +21,12 @@ import com.google.gson.annotations.SerializedName
 import java.util.*
 
 data class Player(
-    // The player's name.
-    // example: Notch
     @SerializedName("name")
     val name: String,
 
-    // The player's UUID.
-    // example: 069a79f4-44e9-4726-a5be-fca90e38aaf5
     @SerializedName("id")
     val uuid: UUID,
 
-    // The player's Discord ID.
-    // example: "385441179069579265"
     @SerializedName("discord_id")
     val discordId: String,
 
diff --git a/src/main/kotlin/com/lambda/network/mojang/GetProfile.kt b/src/main/kotlin/com/lambda/network/mojang/GetProfile.kt
@@ -28,8 +28,6 @@ import java.util.*
  *
  * Example:
  *  - name: jeb_
- *
- * @return result of [GameProfile]
  */
 suspend fun getProfile(name: String) = runCatching {
     LambdaHttp.get("https://api.mojang.com/users/profiles/minecraft/$name").body<GameProfile>()
@@ -40,8 +38,6 @@ suspend fun getProfile(name: String) = runCatching {
  *
  * Example:
  *  - name: ab24f5d6-dcf1-45e4-897e-b50a7c5e7422
- *
- * @return result of [GameProfile]
  */
 suspend fun getProfile(uuid: UUID) = runCatching {
     LambdaHttp.get("https://api.minecraftservices.com/minecraft/profile/lookup/$uuid").body<GameProfile>()
diff --git a/src/main/kotlin/com/lambda/threading/Hook.kt b/src/main/kotlin/com/lambda/threading/Hook.kt
@@ -21,59 +21,9 @@ import kotlin.concurrent.thread
 
 /**
  * Registers a shutdown hook to execute the specified [block] of code when the application is shutting down.
- * This function ensures that the given [block] will be executed before the JVM terminates, allowing graceful cleanup
- * or finalization tasks to be performed.
  *
- * @param block the code to be executed on shutdown.
- *
- * ## Usage:
- * ```
- * onShutdown {
- *     // Perform cleanup tasks or finalizations here
- *     println("Shutting down gracefully...")
- * }
- * ```
- *
- * ## Advantages:
- * - Provides a convenient and reliable mechanism for executing cleanup tasks when the application exits.
- * - Helps ensure that critical resources are released properly, preventing resource leaks or data corruption.
- * - Can be used to handle cleanup in various scenarios, such as closing open connections, saving application state,
- *   or logging shutdown events.
- *
- * ## Code Examples:
- * 1. Registering a simple shutdown hook:
- *    ```
- *    onShutdown {
- *        println("Performing cleanup...")
- *    }
- *    ```
- * 2. Performing resource cleanup on shutdown:
- *    ```
- *    onShutdown {
- *        databaseConnection.close()
- *        fileWriter.close()
- *        println("Resources closed successfully.")
- *    }
- *    ```
- *
- * ## What Not to Do:
- * - Avoid performing time-consuming or blocking operations inside the shutdown hook, as it may delay the shutdown process
- *   and lead to undesirable behavior.
- * - Do not rely solely on shutdown hooks for critical tasks that must be executed reliably. Consider using other
- *   mechanisms such as proper exception handling or manual cleanup where necessary.
- * - Avoid registering multiple shutdown hooks for the same purpose, as it may result in unexpected behavior or conflicts
- *   between the hooks.
- *
- * ## Edge Cases:
- * - If the JVM is terminated abruptly or forcefully (e.g., via `kill -9` on Unix-like systems), the shutdown hooks may
- *   not have a chance to run, leading to potential resource leaks or incomplete cleanup. This is a rare scenario but
- *   should be considered when designing critical cleanup tasks.
- * - In certain environments or configurations where the JVM shutdown process is interrupted or bypassed, such as when
- *   running in a containerized environment where the container itself is forcibly stopped, the shutdown hooks may not
- *   execute as expected. It's important to be aware of the behavior of the runtime environment and handle such cases
- *   accordingly, possibly by implementing additional cleanup mechanisms or relying on external systems for graceful
- *   shutdown coordination.
- */
+ * @see <a href="https://docs.oracle.com/javase/8/docs/technotes/guides/lang/hook-design.html">Design of the Shutdown Hooks API</a>
+*/
 inline fun onShutdown(crossinline block: () -> Unit) {
     Runtime.getRuntime().addShutdownHook(thread(start = false) { block() })
 }
diff --git a/src/main/kotlin/com/lambda/threading/Threading.kt b/src/main/kotlin/com/lambda/threading/Threading.kt
@@ -31,38 +31,41 @@ import kotlinx.coroutines.launch
 import java.util.concurrent.CompletableFuture
 
 /**
- * Executes a block of code only if the context is safe. A context is considered safe when all the following properties are not null:
+ * Runs the [block] in a safe context.
+ *
+ * A context is considered safe when all the following properties are not null:
  * - [SafeContext.world]
  * - [SafeContext.player]
  * - [SafeContext.interaction]
  * - [SafeContext.connection]
- *
- * If the context is not safe, the function will return null and the block of code will not be executed.
- *
- * @param block The block of code to be executed within the safe context.
- * @return The result of the block execution if the context is safe, null otherwise.
  */
 inline fun <T> runSafe(block: SafeContext.() -> T): T? =
     SafeContext.create()?.run(block)
 
+/**
+ * Runs the [block] in an automated context.
+ *
+ * The context contains various settings for various systems.
+ */
 @JvmName("runSafeAutomated0")
 context(safeContext: SafeContext)
 inline fun <T> Automated.runSafeAutomated(automated: Automated = this, block: AutomatedSafeContext.() -> T): T =
     AutomatedSafeContext(safeContext, automated).run(block)
 
+/**
+ * Runs the [block] in an automated context.
+ *
+ * The context contains various settings for various systems.
+ */
 @JvmName("runSafeAutomated1")
 inline fun <T> Automated.runSafeAutomated(block: AutomatedSafeContext.() -> T): T? {
     return AutomatedSafeContext(SafeContext.create() ?: return null, this).run(block)
 }
 
 /**
- * This function is used to execute a block of code on a new thread running asynchronously to the game thread.
- * It should only be used when you need to perform read actions on the game data (not write).
- *
- * Caution: Using this function to write to the game data can lead to race conditions. Therefore, it is recommended
- * to use this function only for read operations to avoid potential concurrency issues.
+ * Runs the [block] in a coroutine.
  *
- * @param block The block of code to be executed concurrently.
+ * Writing to game data is discouraged as it may cause race conditions.
  */
 inline fun runConcurrent(scheduler: CoroutineDispatcher = Dispatchers.Default, crossinline block: suspend CoroutineScope.() -> Unit) =
     EventFlow.lambdaScope.launch(scheduler) {
@@ -80,16 +83,15 @@ inline fun taskContext(crossinline block: suspend CoroutineScope.() -> Unit) =
     }
 
 /**
- * This function is used to execute a block of code within a safe context on a new thread running asynchronously to the game thread.
+ * Runs the [block] within a safe context in a coroutine.
+ *
  * A context is considered safe when all the following properties are not null:
  * - [SafeContext.world]
  * - [SafeContext.player]
  * - [SafeContext.interaction]
  * - [SafeContext.connection]
  *
- * If the context is not safe, the function will not execute the block of code.
- *
- * @param block The block of code to be executed within the safe context.
+ * Writing to game data is discouraged as it may cause race conditions.
  */
 inline fun runSafeConcurrent(crossinline block: suspend SafeContext.() -> Unit) {
     EventFlow.lambdaScope.launch {
@@ -98,40 +100,17 @@ inline fun runSafeConcurrent(crossinline block: suspend SafeContext.() -> Unit)
 }
 
 /**
- * Executes a given task when the render procedure is available.
- *
- * This function is used when a task needs to be performed when the render thread is ready
- * to be used as multiple threads are used simultaneously and the OpenGL context is only available
- * on one thread
+ * Executes a given task before a new render tick begins.
  *
- * Note: This function is non-blocking as the task is scheduled to be executed
- * on the game's main thread, but does not provide any feedback.
- *
- * @param block The task to be executed on the game's main thread.
+ * This function should only be used for synchronization of threads that wish to dispatch
+ * to OpenGL.
  */
 inline fun recordRenderCall(crossinline block: () -> Unit) {
     mc.renderTaskQueue.add { block() }
 }
 
 /**
- * Executes a given task on the game's main thread.
- *
- * This function is used when a task needs to be performed on the game's main thread,
- * as certain operations are not safe to perform on other threads.
- * It uses the Minecraft client's `execute` method to schedule the task.
- *
- * ## Execution Flow:
- * 1. If already on the render thread: Executes the task immediately (zero overhead).
- * 2. Otherwise, schedules the task via Minecraft's [net.minecraft.util.thread.ThreadExecutor]:
- *    a. The task is wrapped in a Runnable and added to a thread-safe queue
- *    b. `LockSupport.unpark` wakes the game thread if it was parked
- *
- * [java.util.concurrent.locks.LockSupport.unpark] will unblock the permit available and allow for execution on that specific thread
- *
- * Note: This function is non-blocking as the task is scheduled to be executed
- * on the game's main thread, but does not provide any feedback.
- *
- * @param block The task to be executed on the game's main thread.
+ * Schedules or executes the [block] on the main thread.
  */
 inline fun runGameScheduled(crossinline block: () -> Unit) {
     if (isOnRenderThread()) {
@@ -143,21 +122,13 @@ inline fun runGameScheduled(crossinline block: () -> Unit) {
 }
 
 /**
- * Executes a given task on the game's main thread within a safe context.
+ * Schedules a task on the main thread within a safe context.
+ *
  * A context is considered safe when all the following properties are not null:
  * - [SafeContext.world]
  * - [SafeContext.player]
  * - [SafeContext.interaction]
  * - [SafeContext.connection]
- *
- * This function is used when a task needs to be performed on the game's main thread,
- * as certain operations are not safe to perform on other threads.
- * It uses the Minecraft client's `execute` method to schedule the task.
- *
- * Note: This function is non-blocking as the task is scheduled to be executed
- * on the game's main thread, but does not provide any feedback.
- *
- * @param block The task to be executed on the game's main thread within a safe context.
  */
 inline fun runSafeGameScheduled(crossinline block: SafeContext.() -> Unit) {
     runGameScheduled { runSafe { block() } }
@@ -166,20 +137,14 @@ inline fun runSafeGameScheduled(crossinline block: SafeContext.() -> Unit) {
 /**
  * Executes a given task on the game's main thread within a safe context
  * and blocks the coroutine until the task is completed.
+ *
  * A context is considered safe when all the following properties are not null:
  * - [SafeContext.world]
  * - [SafeContext.player]
  * - [SafeContext.interaction]
  * - [SafeContext.connection]
  *
- * This function is used when a task needs to be performed on the game's main thread,
- * as certain operations are not safe to perform on other threads.
- *
- * Note:
- * This function is blocking
- * as it uses [CompletableFuture]'s [await] method to [suspend] the coroutine until the task is completed.
- *
- * @param block The task to be executed on the game's main thread within a safe context.
+ * This function blocks until the task is completed.
  */
 suspend inline fun <T> awaitMainThread(noinline block: SafeContext.() -> T) =
     CompletableFuture.supplyAsync({ runSafe { block() } }, mc).await() ?: throw IllegalStateException("Unsafe")

Original file line number	Diff line number	Diff line change
`@@ -30,8 +30,6 @@ import java.util.*`
`30`	`30`	`*`
`31`	`31`	`* Example:`
`32`	`32`	`* - id: ab24f5d6-dcf1-45e4-897e-b50a7c5e7422`
`33`		`- *`
`34`		`- * @return results of cape`
`35`	`33`	`*/`
`36`	`34`	`suspend fun getCape(uuid: UUID) = runCatching {`
`37`	`35`	`LambdaHttp.get("$apiUrl/api/$apiVersion/cape?id=$uuid").body<Cape>()`
Original file line number	Diff line number	Diff line change
`@@ -31,8 +31,6 @@ import io.ktor.http.*`
`31`	`31`	`*`
`32`	`32`	`* Example:`
`33`	`33`	`* - token: OTk1MTU1NzcyMzYxMTQ2NDM4`
`34`		`- *`
`35`		`- * @return result of [Authentication]`
`36`	`34`	`*/`
`37`	`35`	`suspend fun linkDiscord(discordToken: String) = runCatching {`
`38`	`36`	`LambdaHttp.post("${apiUrl}/api/$apiVersion/link/discord") {`
Original file line number	Diff line number	Diff line change
`@@ -29,8 +29,6 @@ import io.ktor.http.*`
`29`	`29`	`*`
`30`	`30`	`* Example:`
`31`	`31`	`* - id: galaxy`
`32`		`- *`
`33`		`- * @return nothing`
`34`	`32`	`*/`
`35`	`33`	`suspend fun setCape(id: String) = runCatching {`
`36`	`34`	`val resp = LambdaHttp.put("$apiUrl/api/$apiVersion/cape?id=$id") {`