Orchestrator.kt has usage examples on everything

src/main/kotlin/Controllers.kt

@@ -41,7 +41,7 @@ interface InputController {
     fun keyPress(keyCode: Int)
 
     /**
-     * Performs a scroll in motion.
+     * Performs a mousewheel scroll in motion.
      *
      * This will move the scroll wheel forward by the number of ticks
      * over the duration. It will sleep for short intervals between
@@ -53,7 +53,7 @@ interface InputController {
     fun scrollIn(sleepDur: Long, sleepDurVariance: Long)
 
     /**
-     * Performs a scroll out motion.
+     * Performs a mousewheel scroll out motion.
      *
      * Same as [scrollIn] but moves the scroll wheel backward.
      */
@@ -75,9 +75,8 @@ interface TemporalController {
     /**
      * Sleeps for the specified duration with some variance.
      *
-     * This will sleep for the given duration plus or minus a random variance.
+     * This will sleep for the given duration plus a random variance between 0 inclusive and [variance] exclusive.
-     * The variance is divided in half to generate a random positive and negative
+     * The variance is divided in half to generate a random positive value that is added to the duration.
-     * value that is added to the duration.
      *
      * If the duration is negative or the variance is less than 1, this method
      * will return immediately without sleeping.
@@ -107,6 +106,16 @@ interface TemporalController {
  * For example, if a target destination point is (100, 200), the wiggle params
  * might generate an actual movement point like (102, 198) to add some randomness.
  *
+ * Usage:
+ *
+ * ```
+ * val controller = DesktopController()
+ * val wiggle = WiggleParams(xWiggle = 10, yWiggle = 15)
+ *
+ * val target = Point(100, 200)
+ * val actual = controller.getAlmostPoint(target, wiggle) // (104, 197)
+ * ```
+ *
  * @param xWiggle The max amount of variance in x direction. Default 25.
  * @param yWiggle The max amount of variance in y direction. Default 25.
  */
@@ -206,28 +215,46 @@ interface Automaton : DesktopController, InputController, TemporalController
  * RobotController aims to provide a simple and easy to use API for
  * automating desktop interactions and workflows.
  *
+ * Usage example:
+ *
+ * ```
+ * val robot = RobotController()
+ *
+ * // Move mouse to 100, 200
+ * robot.mouseMove(Point(100, 200))
+ *
+ * // Left click at current position
+ * robot.click(InputEvent.BUTTON1_MASK)
+ *
+ * // Press A key
+ * robot.keyPress(KeyEvent.VK_A)
+ * ```
+ *
  * @param robot The Robot instance to use. A default is created if not provided.
  */
 open class RobotController(private val robot: Robot = Robot()) : Automaton {
     /**
-     * Moves the mouse cursor to the given [Point].
+     * Moves the mouse cursor to the given [Point] destination.
      *
-     * This uses the Robot [mouseMove] method to move the mouse cursor
+     * Uses the Robot [mouseMove] method to move the mouse cursor to the x and y
-     * to the x and y coordinates specified by the provided [Point] p.
+     * coordinates specified by the provided [Point].
      *
-     * Usage:
+     * Adding some random variance to the target [Point] can simulate human-like
-     *```
+     * imperfect mouse movements.
-     *   val doer = Doer()
      *
-     *   // Create target point
+     * Example usage:
+     *
+     * ```
+     * val robot = RobotController()
+     *
+     * // Target destination point
      * val target = Point(100, 200)
      *
      * // Move mouse to target
-     *   doer.mouseMove(target)
+     * robot.mouseMove(target)
-     *```
+     * ```
      *
-     *
+     * @param destination The [Point] representing the target x and y coordinates.
-     * @param point The [Point] representing the x and y coordinates to move the mouse to.
      */
     override fun moveMouse(point: Point) {
         robot.mouseMove(point.x, point.y)
@@ -241,6 +268,15 @@ open class RobotController(private val robot: Robot = Robot()) : Automaton {
      * A random sleep is added in between pressing and releasing the button
      * to add variance and avoid robotic timing.
      *
+     * Example usage:
+     *
+     * ```
+     * val robot = RobotController()
+     *
+     * // Perform left click at current mouse position
+     * robot.click(InputEvent.BUTTON1_MASK)
+     * ```
+     *
      * @param button The button to click. Must be a valid constant like [InputEvent.BUTTON1_MASK].
      *
      * Returns immediately If button is negative. Button must be a positive integer.
@@ -266,29 +302,49 @@ open class RobotController(private val robot: Robot = Robot()) : Automaton {
      * A random sleep is added after pressing the key before releasing it to add variance
      * and avoid robotic timing.
      *
-     * @param key The key code of the key to press, such as [KeyEvent.VK_A].
+     * Example usage:
      *
-     * returns immediately if key < 0. This can be useful for skipping actions with a -1
+     * ```
+     * val robot = RobotController()
+     *
+     * // Press the 'A' key
+     * robot.keyPress(KeyEvent.VK_A)
+     * ```
+     *
+     * @param keyCode The key code of the key to press, such as [KeyEvent.VK_A].
+     *
+     * Returns immediately if keyCode < 0. This can be useful for skipping actions by passing -1
      */
-    override fun keyPress(key: Int) {
+    override fun keyPress(keyCode: Int) {
         //guardian logic
-        if (key < 0) {
+        if (keyCode < 0) {
             return
         }
 
-        robot.keyPress(key)
+        robot.keyPress(keyCode)
 
         //we add in some random time variance here to appear less robotic
         sleepWithVariance(8, 8)
 
-        robot.keyRelease(key)
+        robot.keyRelease(keyCode)
     }
 
     /**
      * Scrolls the mouse wheel down by one unit.
      *
-     * Uses the Robot [mouseWheel] method to scroll up and then sleeps
+     * Uses the Robot [mouseWheel] method to scroll down and then sleeps
-     * for a random duration between 16-32ms to pace the scrolling.
+     * for a random duration between 10-20ms to pace the scrolling.
+     *
+     * Example usage:
+     *
+     * ```
+     * val robot = RobotController()
+     *
+     * // Scroll down 5 units
+     * repeat(5) {
+     *   robot.scrollDown()
+     * }
+     * ```
      */
     override fun scrollOut(sleepDur: Long, sleepDurVariance: Long) {
         robot.mouseWheel(1)
@@ -298,8 +354,19 @@ open class RobotController(private val robot: Robot = Robot()) : Automaton {
     /**
      * Scrolls the mouse wheel up by one unit.
      *
-     * Uses the Robot [mouseWheel] method to scroll up and then sleeps
+     * Uses the Robot [mouseWheel] method to scroll up and then sleeps for a
-     * for a random duration between 16-32ms to pace the scrolling.
+     * random duration between 10-20ms to pace the scrolling.
+     *
+     * Example usage:
+     *
+     * ```
+     * val robot = RobotController()
+     *
+     * // Scroll up 10 units
+     * repeat(10) {
+     *   robot.scrollUp()
+     * }
+     * ```
      */
     override fun scrollIn(sleepDur: Long, sleepDurVariance: Long) {
         robot.mouseWheel(-1)

src/main/kotlin/Orchestrator.kt

@@ -17,8 +17,14 @@ interface Orchestrator {
     /**
      * Scrolls out to the specified height by repeating scroll in/out operations.
      *
-     * This handles scrolling out by the given height through a series of repeated scroll in and
+     * This handles scrolling out by the given height through a series of repeated
-     * scroll out operations using the [doLoop] method.
+     * scroll in and scroll out operations using the [doLoop] method.
+     *
+     * Example usage:
+     *
+     * ```
+     * orchestrator.scrollOutToHeight(12, 2)
+     * ```
      *
      * @param height The height in game coordinates to scroll out to.
      * @param scrollWaitAndVariance The number of milliseconds to wait between scroll actions.
@@ -44,9 +50,14 @@ interface Orchestrator {
      * The offset points are calculated by moving left/right and up/down from the
      * center point by a fixed offset amount.
      *
+     * Usage Example:
+     * ```
+     * orchestrator.drawStar()
+     * ```
+     *
      * @param p The center point of the star.
      */
-    fun drawStar(p: Point) {
+    fun drawStar(p: Point = automaton.getPointerLocation()) {
         val offset = 100
         val top = Point(p.x, p.y - offset * 2)
         val topright = Point(p.x + offset * 2, p.y + offset)
@@ -71,13 +82,21 @@ interface Orchestrator {
      * Typical usage is to provide a point where something needs to be clicked,
      * along with a sleep duration to wait after clicking.
      *
+     *
+     * Example usage:
+     *
+     * ```
+     * val clickPoint = Point(100, 200)
+     * orchestrator.moveMouseLeftClickAndSleep(clickPoint, 500)
+     * ```
+     *
      * The random variance in sleep time helps match real human actions.
      *
      * @param p The point location to move the mouse and left click.
      * @param sleepDuration The base duration in ms to sleep after clicking.
      * @param sleepDurationVariance The allowed variance in the sleep duration.
      */
-    fun moveMouseLeftClickAndSleep(p: Point, sleepDuration: Long, sleepDurationVariance: Long) {
+    fun moveMouseLeftClickAndSleep(p: Point, sleepDuration: Long, sleepDurationVariance: Long = 1) {
         automaton.moveMouse(p)
         automaton.sleepWithVariance(100, 50)
         //left click
@@ -90,13 +109,21 @@ interface Orchestrator {
      *
      * This method counts down from a provided number of seconds to 0.
      *
-     * It calls the provided [announceFn] function on each step, passing the current
+     * It calls the provided [announceFn] function on each step, passing the current step number.
-     * step number.
-
      * A sleep of 1 second is added between each step.
-
+     *
+     *
      * Typical usage is to print a countdown message within [announceFn].
-
+     *
+     * Usage example:
+     *
+     * ```
+     *
+     * orchestrator.countdown(5) {
+     *   print("\rCountdown: $step     ")
+     * }
+     * ```
+     *
      * @param nSeconds The number of seconds to count down.
      * @param announceFn A callback function called each step, passed step number.
      */
@@ -107,6 +134,8 @@ interface Orchestrator {
         }
     }
 
+
+
     /**
      * Gets the mouse pointer location after a delay.
      *
@@ -119,6 +148,12 @@ interface Orchestrator {
      * The delay helps ensure any prior mouse movements have settled before
      * sampling the location.
      *
+     * Usage example:
+     *
+     * ```
+     * val location = orchestrator.getMouseLocationAfterDelay(5)
+     * println(location) // Prints current mouse location after 5 second delay
+     * ```
      * @param delayInSeconds The number of seconds to wait before sampling pointer location.
      * @return The mouse pointer location after the delay as a Point.
      */
@@ -143,6 +178,14 @@ interface Orchestrator {
      *
      * The delay allows the mouse to settle before sampling its position.
      *
+     * Usage example:
+     *
+     *  ```
+     *  val prompt = "Move mouse to top left corner"
+     *  val pos = orchestrator.promptForMousePosition(prompt)
+     *  println(pos)
+     *  ```
+     *
      * @param prompt The message to display to prompt user to position mouse.
      * @return The Point position of the mouse after user positions it.
      */
@@ -165,6 +208,19 @@ interface Orchestrator {
      *
      * This handles iterating over the loop, tracking progress, and calling the provided task function each iteration.
      *
+     * Typical usage is to pass a task function that performs some unit of work. doLoop() will call that task function
+     * repeatedly to automate a repetitive process.
+     *
+     * Usage example:
+     *
+     * ```
+     * val totalItems = 1000
+     * val itemsPerBatch = 10
+     * orchestrator.doLoop(totalItems, itemsPerBatch){
+     *   // Craft one item
+     * }
+     * ```
+     *
      * @param totalVolume The total number of units that need to be processed.
      * @param volumePerStep The number of units to process per iteration.
      * @param task The function to call each iteration, passing the Orchestrator as argument.

src/main/kotlin/Routines.kt

@@ -80,7 +80,7 @@ object Routines {
         println("\rClean herbs infused")
 
         val finish = System.currentTimeMillis()
-        agent.drawStar(agent.automaton.getPointerLocation())
+        agent.drawStar()
         println("Entire chain finished in ${HelperFunctions.prettyTimeString(finish - start)}")
     }