included usage examples in Controllers.kt

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.
      */
@@ -106,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.
  */
@@ -205,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].
+     *
+     * Adding some random variance to the target [Point] can simulate human-like
+     * imperfect mouse movements.
+     *
+     * Example usage:
      *
-     * Usage:
      * ```
-     *   val doer = Doer()
+     * val robot = RobotController()
      *
-     *   // Create target point
+     * // 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)
@@ -240,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.
@@ -265,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)
@@ -297,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)