it's the weekend. i should be playing video games.

src/main/kotlin/controllers/Automaton.kt

@@ -1,26 +1,16 @@
 package controllers
 
-
 /**
- * Interface for full-featured desktop automation controllers.
+ * Automaton interface defines the core behavior of an automaton object in the system.
  *
- * Automaton combines capabilities from other interfaces to create a controller that can:
+ * An automaton represents a state machine that can react to events and progress through different states over time.
+ * It observes the mouse pointer, time flow-controls, and handles input.
  *
- * - Get desktop and mouse state information like pointer location via [MousePointerObserver]
+ * Automatons should implement the state machine logic and state transitions. They can dispatch actions
+ * and events to other parts of the system.
  *
- * - Perform mouse and keyboard input like clicks, key presses, and scrolling via [InputController]
- *
- * - Handle timing and delays between actions using [TemporalController]
- *
- * By composing multiple capabilities, Automaton aims to provide a simple yet powerful interface for implementing
- * desktop automation routines.
- *
- * Typical usage involves:
- *
- * 1. Obtaining an Automaton instance bound to the current OS/desktop
- * 2. Calling methods like [moveMouse] and [mouseClick] to perform actions
- * 3. Using [sleep] and [sleep] to add delays
- *
- * This interface allows the underlying OS/desktop implementation details to be abstracted and swapped as needed.
+ * This interface extends [MousePointerObserver] to get mouse information, [InputController] to handle input,
+ * and [TemporalController] to control pauses. Classes implementing Automaton should provide the actual state machine
+ * implementation.
  */
 interface Automaton : MousePointerObserver, InputController, TemporalController

src/main/kotlin/controllers/TemporalController.kt

@@ -1,7 +1,6 @@
 package controllers
 
 import java.util.concurrent.TimeUnit
-import kotlin.random.Random
 
 /**
  * Interface for components that control time-related behavior.
@@ -30,7 +29,7 @@ interface TemporalController {
         val duration = if(maxAdditionalDuration == 0L){
             baseDuration
         }else{
-            baseDuration + util.HelperFunctions.getRandomLongFromNormalDistribution((maxAdditionalDuration) / 2)
+            baseDuration + util.HelperFunctions.getRandomLongFromNormalDistribution(maxAdditionalDuration)
         }
 
         TimeUnit.MILLISECONDS.sleep(duration)

src/main/kotlin/util/HelperFunctions.kt

@@ -43,7 +43,8 @@ object HelperFunctions {
      * @return A random long value following an approximate normal distribution
      */
     fun getRandomLongFromNormalDistribution(upperBound: Long): Long{
-        //anything lower to 2 will round down to zero, so return zero
+        // anything lower to 2 will round down to zero, so return zero. Additionally, this guarantees a positive upper
+        //bound in one step
         if(upperBound <= 2L){
             return 0L
         }