From 82acb36334f23cd854e99f3bc53ac8c9ba71cf60 Mon Sep 17 00:00:00 2001
From: dtookey <hocestpotest@gmail.com>
Date: Sun, 10 Sep 2023 19:24:52 -0400
Subject: [PATCH] added some cheap docs

---
 src/main/kotlin/simulation/Simulator.kt       | 30 +++++++-
 .../kotlin/simulation/fifthEd/AttackAction.kt | 71 ++++++++++++++++---
 2 files changed, 87 insertions(+), 14 deletions(-)

diff --git a/src/main/kotlin/simulation/Simulator.kt b/src/main/kotlin/simulation/Simulator.kt
index 7f4efe3..5fb9f8d 100644
--- a/src/main/kotlin/simulation/Simulator.kt
+++ b/src/main/kotlin/simulation/Simulator.kt
@@ -5,7 +5,10 @@ import kotlinx.coroutines.runBlocking
 import java.util.*
 import kotlin.collections.ArrayList
 
-
+/**
+ * Interface for simulation models.
+ * Defines a sample size and simulates individual samples.
+ */
 interface SimulationModel<T : Any> {
     val sampleSize: Int
 
@@ -13,9 +16,18 @@ interface SimulationModel<T : Any> {
     fun simulate(r: Random): T
 }
 
+/**
+ * Interface for running simulations concurrently using multiple threads.
+ * Defines the number of threads to use and runs simulations to generate results.
+ */
 interface Simulator<T : Any> {
 
     companion object {
+        /**
+         * Gets an instance of the Simulator interface implementation.
+         * @param nThreads Number of threads to use for simulations. Defaults to half the available CPU cores.
+         * @return Simulator instance with the specified number of threads.
+         */
         fun <T: Any> getInstance(nThreads: Int = Runtime.getRuntime().availableProcessors() / 2 ): Simulator<T> {
             return SimulatorImpl(nThreads)
         }
@@ -23,6 +35,15 @@ interface Simulator<T : Any> {
 
     val nThreads: Int
 
+    /**
+     * Runs simulations using the provided model and returns the results.
+     *
+     * This divides the sample size into nThreads chunks and runs simulations concurrently on each chunk using coroutines.
+     * The results from each thread are collected into a synchronized list.
+     *
+     * @param model The simulation model to use for generating samples.
+     * @return A list containing all the simulated sample results.
+     */
     fun doSimulation(model: SimulationModel<T>): ArrayList<T> {
         val results = Collections.synchronizedList(ArrayList<T>(model.sampleSize))
 
@@ -53,7 +74,10 @@ interface Simulator<T : Any> {
         return results.toCollection(ArrayList())
     }
 
-
+    /**
+     * Generates simulation results by running [steps] simulations using [model] and [Random].
+     * Returns the results in an [ArrayList].
+     */
     private fun generateResults(steps: Int, model: SimulationModel<T>): ArrayList<T> {
         val results = ArrayList<T>(steps)
         val r = Random()
@@ -65,5 +89,5 @@ interface Simulator<T : Any> {
 
 }
 
-class SimulatorImpl<T : Any>(override val nThreads: Int) :
+internal class SimulatorImpl<T : Any>(override val nThreads: Int) :
     Simulator<T>
\ No newline at end of file
diff --git a/src/main/kotlin/simulation/fifthEd/AttackAction.kt b/src/main/kotlin/simulation/fifthEd/AttackAction.kt
index e29bfd2..784246a 100644
--- a/src/main/kotlin/simulation/fifthEd/AttackAction.kt
+++ b/src/main/kotlin/simulation/fifthEd/AttackAction.kt
@@ -77,7 +77,9 @@ class AttackSimulatorModel(
     }
 }
 
-
+/**
+ * MeleeAttackBuilder builds a [SimpleMeleeAttackAction] by configuring the attack and damage rolls and modifiers.
+ */
 class MeleeAttackBuilder(
     private val attackRollString: String,
     private val dmgRollString: String,
@@ -86,36 +88,83 @@ class MeleeAttackBuilder(
     private val attackModifiers = ArrayList<DiceModifier<Int>>()
     private val damageModifiers = ArrayList<DiceModifier<Int>>()
 
+    /**
+     * Adds a flat bonus to the attack roll.
+     *
+     * @param flat the flat bonus amount to add to or subtract from the attack roll.
+     * @return this MeleeAttackBuilder instance.
+     */
     fun withAtkBonus(flat: Int): MeleeAttackBuilder {
-        attackModifiers.add(FlatModifier(flat))
-        return this
+        return withAtkModifier(FlatModifier(flat))
     }
 
+    /**
+     * Adds a dice-roll bonus to the attack roll.
+     *
+     * @param dice The DiceRoller instance to add as a bonus.
+     * @return This MeleeAttackBuilder instance.
+     */
     fun withAtkBonus(dice: DiceRoller): MeleeAttackBuilder {
-        attackModifiers.add(DiceBonusModifier(dice))
-        return this
+        return withAtkModifier(DiceBonusModifier(dice))
+
     }
 
+    /**
+     * Adds a dice-roll penalty to the attack roll.
+     *
+     * @param dice The DiceRoller instance to add as a penalty. The result will be subtracted from the total.
+     * @return This MeleeAttackBuilder instance.
+     */
     fun withAtkPenalty(dice: DiceRoller): MeleeAttackBuilder {
-        attackModifiers.add(DicePenaltyModifier(dice))
+        return withAtkModifier(DicePenaltyModifier(dice))
+    }
+
+    fun withAtkModifier(modifier: DiceModifier<Int>): MeleeAttackBuilder{
+        attackModifiers.add(modifier)
         return this
     }
 
+    /**
+     * Adds a flat bonus to the damage roll.
+     *
+     * @param flat the flat bonus amount to add to or subtract from the damage roll.
+     * @return this MeleeAttackBuilder instance.
+     */
     fun withDmgBonus(flat: Int): MeleeAttackBuilder {
-        damageModifiers.add(FlatModifier(flat))
-        return this
+        return withDmgModifier(FlatModifier(flat))
+
     }
 
+    /**
+     * Adds a dice-roll bonus to the damage roll.
+     *
+     * @param dice The DiceRoller instance to add as a bonus.
+     * @return This MeleeAttackBuilder instance.
+     */
     fun withDmgBonus(dice: DiceRoller): MeleeAttackBuilder {
-        damageModifiers.add(DiceBonusModifier(dice))
-        return this
+        return withDmgModifier(DiceBonusModifier(dice))
     }
 
+    /**
+     * Adds a dice-roll penalty to the damage roll.
+     *
+     * @param dice The DiceRoller instance to add as a penalty. The result will be subtracted from the total.
+     * @return This MeleeAttackBuilder instance.
+     */
     fun withDmgPenalty(dice: DiceRoller): MeleeAttackBuilder {
-        damageModifiers.add(DicePenaltyModifier(dice))
+        return withDmgModifier(DicePenaltyModifier(dice))
+
+    }
+
+    fun withDmgModifier(modifier: DiceModifier<Int>): MeleeAttackBuilder{
+        this.damageModifiers.add(modifier)
         return this
     }
 
+    /**
+     * Builds and returns a SimpleMeleeAttackAction instance with the configured attack and damage rolls,
+     * modifiers, and defense value.
+     */
     fun build(): SimpleMeleeAttackAction {
         return SimpleMeleeAttackAction(
             ActionRollInfo(