even betterer docs

src/main/kotlin/Doer.kt

@@ -6,22 +6,31 @@ 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.
- *
- * 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)
+ * val nearTarget = doer.getAlmostPoint(target, WiggleParams())
+ * doer.mouseMove(nearTarget)
+ *
+ * // 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 {
 
@@ -30,18 +39,8 @@ class Doer {
      */
     private val robot = Robot()
     companion object {
-
         /**
-         * Mouse button mask for a left mouse click.
-         *
-         * This stores the button mask value from [InputEvent] that represents a left mouse click.
-         *
-         * It can be passed to [click] or other methods that expect a mouse button value.
-         */
-        private const val LEFT_CLICK = InputEvent.BUTTON1_DOWN_MASK
-
-        /**
-         * The duration in milliseconds of one "tick".
+         * The duration in milliseconds of one "tick". The duration of 600ms matches the tick duration of game servers.
          *
          * This defines the concept of a "tick" as a unit of time used for pacing actions.
          *
@@ -53,7 +52,8 @@ class Doer {
         const val TICK_DURATION_MS = 600L
 
         /**
-         * Extra padding in milliseconds added before actions to account for latency.
+         * Extra padding in milliseconds added before actions to account for latency. 500ms is entirely arbitrary. It is
+         * simply a value that works well during high-load periods. Better to be conservative than lossy.
          *
          * This defines an extra duration in milliseconds that is added to sleeps
          * and waits.
@@ -65,15 +65,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)
 
@@ -83,6 +84,18 @@ class Doer {
      * This uses the Robot [mouseMove] method to move the mouse cursor
      * to the x and y coordinates specified by the provided [Point] p.
      *
+     * Usage:
+     *```
+     *   val doer = Doer()
+     *
+     *   // Create target point
+     *   val target = Point(100, 200)
+     *
+     *   // Move mouse to target
+     *   doer.mouseMove(target)
+     *```
+     *
+     *
      * @param p The [Point] representing the x and y coordinates to move the mouse to.
      */
     fun mouseMove(p: Point) {
@@ -101,8 +114,12 @@ class Doer {
      * @param button The mouse button to click, as a button mask from [InputEvent].
      */
     fun click(button: Int) {
+
         robot.mousePress(button)
+
+        //we add in some random time variance here to appear less robotic
         sleep(8, 8)
+
         robot.mouseRelease(button)
     }
 
@@ -118,8 +135,12 @@ class Doer {
      * @param key The key code of the key to press, from [java.awt.event.KeyEvent].
      */
     fun keypress(key: Int) {
+
         robot.keyPress(key)
+
+        //we add in some random time variance here to appear less robotic
         sleep(8, 8)
+
         robot.keyRelease(key)
     }
 
@@ -137,7 +158,8 @@ class Doer {
     fun moveMouseLeftClickAndSleep(p: Point, dur: Long, durRange: Long) {
         mouseMove(p)
         sleep(100, 50)
-        click(LEFT_CLICK)
+        //left click
+        click(InputEvent.BUTTON1_DOWN_MASK)
         sleep(dur, durRange)
     }