even more docs for Doer

src/main/kotlin/Doer.kt

@@ -5,14 +5,61 @@ import java.awt.event.InputEvent
 import java.util.concurrent.TimeUnit
 import kotlin.random.Random
 
+/**
+ * Class providing methods for programmatic control of mouse and keyboard.
+ *
+ * This uses a Robot instance to facilitate actions like mouse movements,
+ * clicks, scrolls, and key presses.
+ *
+ * It contains utility methods to perform actions in a human-like way,
+ * including random pacing and wiggle to avoid robotic movement.
+ *
+ * Typical usage:
+ *
+ * ```
+ * val doer = Doer()
+ * doer.mouseMove(Point(100, 200))
+ * doer.click(InputEvent.BUTTON1_DOWN_MASK)
+ * ```
+ */
 class Doer {
+
+    /**
+     * The Robot instance used to perform mouse and keyboard actions.
+     */
     private val robot = Robot()
     companion object {
-        // The mouse button mask for a left click
+
-        const val LeftClick = InputEvent.BUTTON1_DOWN_MASK
+        /**
-        // The duration in ms of one "tick" used for pacing actions
+         * 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".
+         *
+         * This defines the concept of a "tick" as a unit of time used for pacing actions.
+         *
+         * It is used in methods like [sleepForNTicks] to calculate sleep durations
+         * based on multiplying a number of ticks by this value.
+         *
+         * For example, 5 ticks with this value would be 5 * 600 = 3000ms sleep duration.
+         */
         const val TICK_DURATION_MS = 600L
-        // Extra padding in ms added before actions to account for latency
+
+        /**
+         * Extra padding in milliseconds added before actions to account for latency.
+         *
+         * This defines an extra duration in milliseconds that is added to sleeps
+         * and waits.
+         *
+         * It is to account for latency in the system before actions like mouse moves
+         * and clicks actually take effect.
+         */
         const val LATENCY_PADDING_MS = 500L
     }
 
@@ -79,7 +126,7 @@ class Doer {
      * Moves the mouse to a point, left clicks, and sleeps.
      *
      * This moves the mouse to the given [Point] p, sleeps for 100ms ± 50ms,
-     * left clicks using [LeftClick], and then sleeps for the given duration
+     * left clicks using [LEFT_CLICK], and then sleeps for the given duration
      * dur ± durRange.
      *
      * @param p The [Point] to move the mouse to.
@@ -89,7 +136,7 @@ class Doer {
     fun moveMouseLeftClickAndSleep(p: Point, dur: Long, durRange: Long) {
         mouseMove(p)
         sleep(100, 50)
-        click(LeftClick)
+        click(LEFT_CLICK)
         sleep(dur, durRange)
     }