even betterer docs

src/main/kotlin/Doer.kt

@@ -12,9 +12,6 @@ import kotlin.random.Random
  * through a [Robot] instance. It includes utility methods to add less-robotic
  * variance and pacing to the actions.
  *
- * For example, methods like [getAlmostPoint] and the random sleeps in
- * [click] and [keypress] help make the automated interactions less robotic.
- *
  * Basic usage:
  *
  * ```
@@ -22,7 +19,8 @@ import kotlin.random.Random
  *
  * // Move mouse
  * val target = Point(100, 200)
- * doer.mouseMove(target)
+ * val nearTarget = doer.getAlmostPoint(target, WiggleParams())
+ * doer.mouseMove(nearTarget)
  *
  * // Mouse click
  * doer.click(Doer.LEFT_CLICK)
@@ -41,18 +39,8 @@ class Doer {
      */
     private val robot = Robot()
     companion object {
-
         /**
-         * Mouse button mask for a left mouse click.
+         * The duration in milliseconds of one "tick". The duration of 600ms matches the tick duration of game servers.
-         *
-         * 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".
          *
          * This defines the concept of a "tick" as a unit of time used for pacing actions.
          *
@@ -64,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.
@@ -95,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) {
@@ -113,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)
-        sleep(8, 8) //trying to mimic the physiology of pressing and releasing with a clumsy ape finger
+
+        //we add in some random time variance here to appear less robotic
+        sleep(8, 8)
+
         robot.mouseRelease(button)
     }
 
@@ -130,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)
-        sleep(8, 8) //trying to mimic the physiology of pressing and releasing with a clumsy ape finger
+
+        //we add in some random time variance here to appear less robotic
+        sleep(8, 8)
+
         robot.keyRelease(key)
     }
 
@@ -149,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)
     }