From fdefd2df08d75d12d709df4a7e837562e3173805 Mon Sep 17 00:00:00 2001
From: dtookey <hocestpotest@gmail.com>
Date: Thu, 3 Aug 2023 11:56:54 -0400
Subject: [PATCH] better docs? maybe?

---
 src/main/kotlin/Doer.kt | 40 ++++++++++++++++++++++++++--------------
 1 file changed, 26 insertions(+), 14 deletions(-)

diff --git a/src/main/kotlin/Doer.kt b/src/main/kotlin/Doer.kt
index 6e9e211..ae620bd 100644
--- a/src/main/kotlin/Doer.kt
+++ b/src/main/kotlin/Doer.kt
@@ -6,22 +6,33 @@ import java.util.concurrent.TimeUnit
 import kotlin.random.Random
 
 /**
- * Class providing methods for programmatic control of mouse and keyboard.
+ * Utility class for programmatically controlling mouse and keyboard actions.
  *
- * This uses a Robot instance to facilitate actions like mouse movements,
- * clicks, scrolls, and key presses.
+ * This class allows performing mouse movements, clicks, and keyboard presses
+ * through a [Robot] instance. It includes utility methods to add less-robotic
+ * variance and pacing to the actions.
  *
- * It contains utility methods to perform actions in a human-like way,
- * including random pacing and wiggle to avoid robotic movement.
+ * For example, methods like [getAlmostPoint] and the random sleeps in
+ * [click] and [keypress] help make the automated interactions less robotic.
  *
- * Typical usage:
+ * Basic usage:
  *
  * ```
  * val doer = Doer()
- * val nearbyPoint = doer.getAlmostPoint(Point(100, 200), WiggleParams(50, 50))
- * doer.mouseMove(nearbyPoint)
- * doer.click(InputEvent.BUTTON1_DOWN_MASK)
+ *
+ * // Move mouse
+ * val target = Point(100, 200)
+ * doer.mouseMove(target)
+ *
+ * // Mouse click
+ * doer.click(Doer.LEFT_CLICK)
+ *
+ * // Type keys
+ * doer.keypress(KeyEvent.VK_A)
+ * doer.keypress(KeyEvent.VK_B)
  * ```
+ *
+ * @constructor Creates a Doer instance with a Robot.
  */
 class Doer {
 
@@ -65,15 +76,16 @@ class Doer {
     }
 
     /**
-     * Data class to hold parameters for random wiggle amounts when moving the mouse.
+     * Data class to hold parameters for random wiggle amounts when moving the mouse. This is useful for avoiding
+     * "robotic" location patterns on the screen. You'll still converge into an absolutely perfect box, but meh.
      *
      * This holds the maximum x and y wiggle offset values to use when randomly
      * offsetting mouse movements to make them less robotic.
      *
      * For example, this could be passed to [getAlmostPoint] to control the randomization.
      *
-     * @param xWiggle The max x offset, default 25.
-     * @param yWiggle The max y offset, default 25.
+     * @param xWiggle The max x offset for both parities. So a xWiggle value of 5 will result in a value of x +/- 5, default 25.
+     * @param yWiggle The max y offset for both parities. So a yWiggle value of 5 will result in a value of y +/- 5, default 25.
      */
     data class WiggleParams(val xWiggle: Int = 25, val yWiggle: Int = 25)
 
@@ -102,7 +114,7 @@ class Doer {
      */
     fun click(button: Int) {
         robot.mousePress(button)
-        sleep(8, 8)
+        sleep(8, 8) //trying to mimic the physiology of pressing and releasing with a clumsy ape finger
         robot.mouseRelease(button)
     }
 
@@ -119,7 +131,7 @@ class Doer {
      */
     fun keypress(key: Int) {
         robot.keyPress(key)
-        sleep(8, 8)
+        sleep(8, 8) //trying to mimic the physiology of pressing and releasing with a clumsy ape finger
         robot.keyRelease(key)
     }