Improvement: Manager and build sim docs

src/main/kotlin/com/lambda/interaction/construction/context/BuildContext.kt

@@ -25,6 +25,9 @@ import net.minecraft.block.BlockState
 import net.minecraft.util.hit.BlockHitResult
 import net.minecraft.util.math.BlockPos
 
+/**
+ * Holds the necessary information for managers to perform actions.
+ */
 abstract class BuildContext : Comparable<BuildContext>, Drawable, Automated {
     abstract val hitResult: BlockHitResult
     abstract val rotationRequest: RotationRequest

src/main/kotlin/com/lambda/interaction/construction/processing/PlacementProcessor.kt

@@ -20,6 +20,11 @@ package com.lambda.interaction.construction.processing
 import net.minecraft.block.BlockState
 import net.minecraft.util.math.BlockPos
 
+/**
+ * The class all pre-processors must extend to provide the structure. Preprocessors are used to
+ * optimize how blocks are simulated. Some blocks might only be placeable on certain sides, so it is
+ * unnecessary to scan all of them, for example.
+ */
 abstract class PlacementProcessor {
     abstract fun acceptsState(state: BlockState): Boolean
     abstract fun preProcess(state: BlockState, pos: BlockPos, accumulator: PreProcessingInfoAccumulator)

src/main/kotlin/com/lambda/interaction/construction/processing/ProcessorRegistry.kt

@@ -29,6 +29,10 @@ object ProcessorRegistry : Loadable {
     private val processors = getInstances<PlacementProcessor>()
     private val processorCache = Collections.synchronizedMap<BlockState, PreProcessingInfo?>(mutableMapOf())
 
+    /**
+     * List of properties that can be processed after the block is placed. This is often used to ignore these properties
+     * when placing blocks, as sometimes they can only be set to the right state after placement.
+     */
     val postProcessedProperties = setOf(
         Properties.EXTENDED,
         Properties.EYE,
@@ -106,6 +110,13 @@ object ProcessorRegistry : Loadable {
 
     override fun load() = "Loaded ${processors.size} pre processors"
 
+    /**
+     * [PreProcessingInfo]'s are cached to avoid duplicate computations as block states are immutable.
+     *
+     * @return A [PreProcessingInfo] object containing information about the block state. This method runs through
+     * each pre-processor checking if the state can be accepted. If so, the state is passed through the pre-processor
+     * which can call the functions within the [PreProcessingInfoAccumulator] DSL to modify the information.
+     */
     fun TargetState.getProcessingInfo(pos: BlockPos): PreProcessingInfo? =
         if (this !is TargetState.State) PreProcessingInfo.DEFAULT
         else {

src/main/kotlin/com/lambda/interaction/construction/result/Contextual.kt

@@ -20,6 +20,9 @@ package com.lambda.interaction.construction.result
 import com.lambda.interaction.construction.context.BuildContext
 import com.lambda.interaction.request.hotbar.HotbarManager
 
+/**
+ * Represents a result holding a [BuildContext].
+ */
 interface Contextual : ComparableResult<Rank> {
     val context: BuildContext
 

src/main/kotlin/com/lambda/interaction/construction/result/Dependent.kt

@@ -17,6 +17,9 @@
 
 package com.lambda.interaction.construction.result
 
+/**
+ * Represents a [BuildResult] that depends on another [BuildResult].
+ */
 interface Dependent {
     val dependency: BuildResult
     val lastDependency: BuildResult

src/main/kotlin/com/lambda/interaction/construction/result/Drawable.kt

@@ -19,6 +19,9 @@ package com.lambda.interaction.construction.result
 
 import com.lambda.graphics.renderer.esp.ShapeBuilder
 
+/**
+ * Represents a [BuildResult] that can be rendered in-game.
+ */
 interface Drawable {
     fun ShapeBuilder.buildRenderer()
 }

src/main/kotlin/com/lambda/interaction/construction/result/Navigable.kt

@@ -19,6 +19,9 @@ package com.lambda.interaction.construction.result
 
 import baritone.api.pathing.goals.Goal
 
+/**
+ * Represents a [BuildResult] with a pathing goal.
+ */
 interface Navigable {
     val goal: Goal
 }

src/main/kotlin/com/lambda/interaction/construction/result/Resolvable.kt

@@ -20,6 +20,9 @@ package com.lambda.interaction.construction.result
 import com.lambda.context.Automated
 import com.lambda.task.Task
 
+/**
+ * Represents a [BuildResult] with a resolvable [Task]
+ */
 interface Resolvable {
     context(automated: Automated)
     fun resolve(): Task<*>

src/main/kotlin/com/lambda/interaction/construction/result/results/InteractResult.kt

@@ -30,6 +30,10 @@ import net.minecraft.util.math.BlockPos
 sealed class InteractResult : BuildResult() {
     override val name: String get() = "${this::class.simpleName} at ${pos.toShortString()}"
 
+    /**
+     * Represents a successful interaction. All checks have been passed.
+     * @param context The context of the interaction.
+     */
     data class Interact(
         override val pos: BlockPos,
         override val context: InteractionContext

src/main/kotlin/com/lambda/interaction/construction/result/results/PostSimResult.kt

@@ -24,6 +24,9 @@ import net.minecraft.util.math.BlockPos
 sealed class PostSimResult : BuildResult() {
     override val name: String get() = "${this::class.simpleName} at ${pos.toShortString()}"
 
+    /**
+     * No result can be found for the given position.
+     */
     data class NoMatch(
         override val pos: BlockPos,
     ) : PostSimResult() {

src/main/kotlin/com/lambda/interaction/construction/simulation/BuildSimulator.kt

@@ -34,7 +34,22 @@ import kotlinx.coroutines.runBlocking
 import kotlinx.coroutines.supervisorScope
 import net.minecraft.util.math.Vec3d
 
+/**
+ * The public API for simulating a blueprint.
+ */
 object BuildSimulator : Sim<PostSimResult>() {
+    /**
+     * Iterates over the blueprint and performs the best suited simulation. Each simulation adds [BuildResult]s to
+     * the provided concurrent set. This method uses coroutines to perform the simulations in parallel. The results
+     * will likely not be returned in the same order they were simulated due to the parallel nature of the simulations.
+     *
+     * @return A set of [BuildResult]s
+     *
+     * @see ISimInfo.sim
+     * @see simPostProcessing
+     * @see simPlacement
+     * @see simBreak
+     */
     context(automatedSafeContext: AutomatedSafeContext)
     fun Blueprint.simulate(
         pov: Vec3d = automatedSafeContext.player.eyePos

src/main/kotlin/com/lambda/interaction/construction/simulation/ISimInfo.kt

@@ -29,6 +29,10 @@ import net.minecraft.util.math.BlockPos
 import net.minecraft.util.math.Vec3d
 import java.util.*
 
+/**
+ * An interface representing all the information required to simulate a state. All simulators must present their public api
+ * as an extension of the [SimInfo] class to allow easy access through the DSL style sim builder.
+ */
 interface ISimInfo : Automated {
     val pos: BlockPos
     val state: BlockState
@@ -39,6 +43,9 @@ interface ISimInfo : Automated {
     val dependencyStack: Stack<Sim<*>>
 
     companion object {
+        /**
+         * Creates a [SimInfo], checks its basic requirements, and runs the [simBuilder] block.
+         */
         @SimDsl
         context(_: BuildSimulator)
         suspend fun AutomatedSafeContext.sim(
@@ -56,6 +63,11 @@ interface ISimInfo : Automated {
             ).takeIf { it.hasBasicRequirements() }?.run { simBuilder() }
         }
 
+        /**
+         * Creates a new [SimInfo] using the current [ISimInfo]'s [dependencyStack] and [concurrentResults],
+         * checks its basic requirements, and runs the [simBuilder] block. As simulations tend to make use of
+         * concurrency, a new stack is created and the dependencies from the previous stack are added.
+         */
         @SimDsl
         context(_: AutomatedSafeContext)
         suspend fun ISimInfo.sim(

src/main/kotlin/com/lambda/interaction/construction/simulation/Sim.kt

@@ -41,11 +41,40 @@ import kotlin.math.pow
 @DslMarker
 annotation class SimDsl
 
+/**
+ * A class designed to simulate transforming a BlockState at a specified BlockPos to
+ * a TargetState.
+ *
+ * Some [Sim]s might need to call other sims as an intermediary between the current BlockState
+ * and the TargetState. In this case, we use a dependency system to ensure type safety.
+ * All sims must only return either [GenericResult]s or typed [BuildResult]s. For example, the BreakSim
+ * must only return BreakResults. For this reason, each type has its own Dependency result.
+ * To make sure that the results added are of the correct type, each [Sim] must be called from another [Sim].
+ * Assuming the dependency stack has not reached max capacity, the original sim is then added to the dependency stack
+ * kept within the [SimInfo] object. Each [BuildResult] added is then iterated over the dependency stack, calling
+ * [dependentUpon] on each one. By the end, the result will be a nested group, with your initial [BuildResult] at
+ * the very bottom, which is then added to the [ISimInfo.concurrentResults] set. After a sim is completed, the dependency
+ * is then popped from the stack.
+ *
+ * @param T The type of [BuildResult] this sim produces.
+ *
+ * @see com.lambda.interaction.construction.result.Dependent
+ * @see dependentUpon
+ * @see withDependent
+ */
 @SimDsl
 abstract class Sim<T : BuildResult> : Results<T> {
+    /**
+     * Can be overridden to return a typed Dependent result with the initial [buildResult] nested inside.
+     *
+     * @see com.lambda.interaction.construction.result.Dependent
+     */
     @SimDsl
     open fun dependentUpon(buildResult: BuildResult): BuildResult = buildResult
 
+    /**
+     * Pushes and pops the [dependent] onto and off of the dependency stack unless the [maxSimDependencies] is reached.
+     */
     protected suspend fun ISimInfo.withDependent(dependent: Sim<*>, block: suspend () -> Unit) {
         // +1 because the build sim counts as a dependent
         if (dependencyStack.size >= maxSimDependencies + 1) return
@@ -54,6 +83,11 @@ abstract class Sim<T : BuildResult> : Results<T> {
         dependencyStack.pop()
     }
 
+    /**
+     * Scans a [voxelShape] on the given [sides] at the [pos] from the [pov].
+     *
+     * @return A set of [CheckedHit]
+     */
     suspend fun ISimInfo.scanShape(
         pov: Vec3d,
         voxelShape: VoxelShape,
@@ -91,7 +125,7 @@ abstract class Sim<T : BuildResult> : Results<T> {
                         }
 
                         if (hit.blockPos != pos || hit.side != side) return@scanSurfaces
-                        val checked = CheckedHit(hit, newRotation, buildConfig.interactReach)
+                        val checked = CheckedHit(hit, newRotation)
 
                         validHits.add(checked)
                     }

src/main/kotlin/com/lambda/interaction/construction/simulation/checks/BasicChecker.kt

@@ -29,6 +29,9 @@ import com.lambda.util.world.WorldUtils.isLoaded
 import net.minecraft.block.OperatorBlock
 
 object BasicChecker : Results<PreSimResult> {
+    /**
+     * A sequence of basic checks to make sure that the block is worth simulating.
+     */
     @SimDsl
     context(automatedSafeContext: AutomatedSafeContext)
     fun SimInfo.hasBasicRequirements(): Boolean = with(automatedSafeContext) {

src/main/kotlin/com/lambda/interaction/construction/simulation/checks/BreakSim.kt

@@ -73,6 +73,9 @@ class BreakSim private constructor(simInfo: ISimInfo)
         BreakResult.Dependency(pos, buildResult)
 
     companion object {
+        /**
+         * Public [SimDsl] API.
+         */
         @SimDsl
         context(automatedSafeContext: AutomatedSafeContext, dependent: Sim<*>)
         suspend fun SimInfo.simBreak() =

src/main/kotlin/com/lambda/interaction/construction/simulation/checks/PlaceSim.kt

@@ -76,6 +76,9 @@ class PlaceSim private constructor(simInfo: ISimInfo)
         PlaceResult.Dependency(pos, buildResult)
 
     companion object {
+        /**
+         * Public [SimDsl] API.
+         */
         context(automatedSafeContext: AutomatedSafeContext, dependent: Sim<*>)
         @SimDsl
         suspend fun SimInfo.simPlacement() =

src/main/kotlin/com/lambda/interaction/construction/simulation/checks/PostProcessingSim.kt

@@ -52,6 +52,9 @@ class PostProcessingSim private constructor(simInfo: ISimInfo)
         InteractResult.Dependency(pos, buildResult)
 
     companion object {
+        /**
+         * Public [SimDsl] API.
+         */
         context(automatedSafeContext: AutomatedSafeContext, dependent: Sim<*>)
         @SimDsl
         suspend fun SimInfo.simPostProcessing() =

src/main/kotlin/com/lambda/interaction/request/ActionInfo.kt

@@ -19,6 +19,10 @@ package com.lambda.interaction.request
 
 import com.lambda.interaction.construction.context.BuildContext
 
+/**
+ * A simple interface to provide a basic object to hold key information that managers might need if information
+ * must persist longer than the request.
+ */
 interface ActionInfo {
     val context: BuildContext
     val pendingInteractionsList: MutableCollection<BuildContext>

src/main/kotlin/com/lambda/interaction/request/DebugLogger.kt

@@ -35,6 +35,9 @@ import imgui.flag.ImGuiWindowFlags
 import java.awt.Color
 import java.util.*
 
+/**
+ * A simple logger that can be used to display information about what is happening within the managers.
+ */
 class DebugLogger(
     val name: String
 ) {

src/main/kotlin/com/lambda/interaction/request/PositionBlocking.kt

@@ -19,6 +19,11 @@ package com.lambda.interaction.request
 
 import net.minecraft.util.math.BlockPos
 
+/**
+ * Provides a [blockedPositions] list to inform other managers what positions should not be processed.
+ *
+ * Reasons a position could be blocked include pending interactions and or active interactions.
+ */
 interface PositionBlocking {
     val blockedPositions: List<BlockPos>
 }

src/main/kotlin/com/lambda/interaction/request/PostActionHandler.kt

@@ -25,6 +25,9 @@ import com.lambda.event.listener.UnsafeListener.Companion.listenUnsafe
 import com.lambda.interaction.request.breaking.BrokenBlockHandler
 import com.lambda.util.collections.LimitedDecayQueue
 
+/**
+ * A simple interface for handlers of actions that need some sort of server response after being executed.
+ */
 abstract class PostActionHandler<T : ActionInfo> {
     abstract val pendingActions: LimitedDecayQueue<T>
 

src/main/kotlin/com/lambda/interaction/request/Request.kt

@@ -19,8 +19,15 @@ package com.lambda.interaction.request
 
 import com.lambda.context.Automated
 
+/**
+ * A simple format to ensure basic requirements and information when requesting a manager.
+ *
+ * @property requestId Used for tracking how many requests there have been and what number this request is.
+ * @property fresh If this request is new.
+ * @property done If this request has been completed.
+ */
 abstract class Request : Automated {
-    abstract val requestID: Int
+    abstract val requestId: Int
     var fresh = true
 
     abstract val done: Boolean