RSLogic.kt has usage examples on everything

src/main/kotlin/Entry.kt

@@ -2,6 +2,7 @@ import java.awt.Point
 
 fun main() {
 //    Routines.fullRunIncense(0, 0, 0, 257)
-    Routines.processInventoryAtFurnace(3566)
+//    Routines.processInventoryAtFurnace(3566)
+    println(HelperFunctions.prettyTimeString(72134))
 }
 

src/main/kotlin/HelperFunctions.kt

@@ -5,6 +5,17 @@ object HelperFunctions {
     /**
      * Computes the total number of steps needed to process the given total volume.
      *
+     * This takes the total volume that needs to be processed and th
+     * and calculates the total steps required.
+     * Usage examples:
+     * ```
+     * val total = 550
+     * val perStep = 200
+     * val steps = calculateTotalSteps(total, perStep) // 3 steps
+     *
+     * val steps = calculateTotalSteps(1000, 100) // 10 steps
+     * ```
+     *
      * @param totalVolume the total amount that needs to be processed
      * @param volumePerStep the amount to process per step
      * @return the number of steps required to process the total volume
@@ -20,6 +31,21 @@ object HelperFunctions {
     /**
      * Prints a progress report to console showing current step, total steps, elapsed time, and estimated remaining time.
      *
+     * This takes the current step number, total steps, and elapsed duration and prints a progress report.
+     * Typical usage is to call this within a loop, passing the loop index for current step and total loop count.
+     *
+     *
+     * Usage example:
+     * ```
+     * val totalSteps = 100
+     * val start = System.currentTimeMillis()
+     * for (i in 1..totalSteps) {
+     *   // Do work
+     *
+     *   report(i, totalSteps, System.currentTimeMillis() - start)
+     * }
+     * ```
+     *
      * @param step The current step number
      * @param of The total number of steps
      * @param dur The elapsed duration so far in milliseconds
@@ -32,6 +58,16 @@ object HelperFunctions {
     /**
      * Converts a duration in milliseconds to a human-readable string.
      *
+     * This takes a duration in ms and converts it to a formatted string like "2h13m4s".
+     *
+     * Usage example:
+     *
+     * ```
+     * val duration = 72134 // ms
+     * val timeStr = prettyTimeString(duration)
+     * // "1m12s"
+     * ```
+     *
      * @param durationMillis The duration to convert, in milliseconds
      * @return A string representation of the duration, in the format XhYmZs
      */
@@ -61,9 +97,10 @@ object HelperFunctions {
      * It then formats this location into a string declaring a val with the provided
      * variable name, like:
      *
-     * ```
+     *  ```
-     * val myPoint = Point(123, 456)
+     *  val location = getPointerLocationAsValDeclarationString("clickPoint")
-     * ```
+     *  // val clickPoint = Point(123, 456)
+     *  ```
      *
      * The delay before getting the pointer location helps ensure the mouse has
      * settled after any prior movements.

src/main/kotlin/RSLogic.kt

@@ -9,6 +9,13 @@ import java.awt.event.KeyEvent
  *
  * Implementations will contain the game-specific logic to interact with the
  * RuneScape client and APIs to carry out the actions.
+ *
+ * Usage example:
+ * ```
+ * val orch = RSOrchestrator.getInstance()
+ * val params = StandingTaskParams(...)
+ * orch.doStandingTask(orch, params)
+ * ```
  */
 interface RSOrchestrator : Orchestrator {
     companion object {
@@ -21,6 +28,13 @@ interface RSOrchestrator : Orchestrator {
          * It withdraws items from the bank, crafts a batch of items, deposits crafted items,
          * and repeats.
          *
+         * Usage example:
+         * ```
+         * val orch = RSOrchestrator.getInstance()
+         * val params = StandingTaskParams(...)
+         * orch.doStandingTask(orch, params)
+         * ```
+         *
          * @param orchestrator The [RSOrchestrator] that will execute the actions.
          * @param params The [StandingTaskParams] configuring the task details.
          * @return Unit.
@@ -42,6 +56,14 @@ interface RSOrchestrator : Orchestrator {
          *
          * It will repeat this loop for the specified total volume of items to craft, doing the given volume per loop iteration.
          *
+         *  Usage example:
+         *
+         *  ```
+         *  val orch = RSOrchestrator.getInstance()
+         *  val params = TravelTaskParams(...)
+         *  orch.doTravelTask(orch, params)
+         *  ```
+         *
          * @param orchestrator The [RSOrchestrator] instance that will execute the actual actions.
          * @param params The [TravelTaskParams] configuring the crafting loop details.
          * @return Unit.
@@ -77,6 +99,12 @@ interface RSOrchestrator : Orchestrator {
      * - Clicks the default "Make" hotkey to start crafting.
      * - Waits for the specified crafting duration plus random variance.
      *
+     * Usage example:
+     * ```
+     * val params = StandingTaskParams(...)
+     * orchestrator.processAtBank(params)
+     * ```
+     *
      * @param taskParams The StandingTaskParams configuring the task details like bank location, hotkeys, durations etc.
      */
     fun processAtBank(
@@ -101,6 +129,18 @@ interface RSOrchestrator : Orchestrator {
      * - Clicks the "Make" button using the hotkey to craft items.
      * - Waits for the randomized crafting duration.
      *
+     * Usage example:
+     * ```
+     * val params = TravelTaskParams(
+     *   bankLocation = Point(100, 200),
+     *   stationLocation = Point(300, 400),
+     *   withdrawHotkey = KeyEvent.VK_F1,
+     *   craftHotkey = KeyEvent.VK_2,
+     *   // ...other params
+     * )
+     * orchestrator.processAtStationNearBank(params)
+     * ```
+     *
      * @param taskParams The TravelTaskParams configuring the task details like locations, durations, hotkeys etc.
      */
     fun processAtStationNearBank(
@@ -108,9 +148,23 @@ interface RSOrchestrator : Orchestrator {
     )
 
     /**
-     * Gets the bank location point.
+     * Gets the screen point location of the bank.
      *
-     * @return The [Point] representing the x,y screen coordinates of the bank location.
+     * This returns the x,y screen coordinates where the bank is located, which can be used to interact with the bank.
+     *
+     * Usage:
+     *
+     * ```
+     * val bankPoint = orchestrator.getBankLocation()
+     *
+     * // Left click the bank location to open the interface
+     * orchestrator.moveMouseLeftClickAndSleep(bankPoint, 100)
+     *
+     * // Withdraw preset inventory at bank
+     * orchestrator.keyPress(KeyEvent.VK_F1)
+     * ```
+     *
+     * @return The Point representing the x,y screen coordinates of the bank location.
      */
     fun getBankPoint(): Point
 }
@@ -121,6 +175,20 @@ interface RSOrchestrator : Orchestrator {
  * This class handles executing RuneScape automation tasks by controlling
  * the game client via image recognition and input emulation.
  *
+ * Usage examples:
+ * Travel between bank and crafting station:
+ * ```
+ * val agent = RSAgent.getInstance()
+ * val travelParams = TravelTaskParams(...)
+ * agent.doTravelTask(agent, travelParams)
+ * ```
+ * Craft while standing at bank:
+ * ```
+ * val standingParams = StandingTaskParams(...)
+ * agent.doStandingTask(agent, standingParams)
+ * ```
+ *
+ *
  * @param automaton The [Automaton] instance used to control the game. Defaults to [RobotController].
  */
 private class RSAgent(override val automaton: Automaton = RobotController()) : RSOrchestrator {
@@ -166,6 +234,13 @@ private class RSAgent(override val automaton: Automaton = RobotController()) : R
      * - Clicks the default "Accept" hotkey to start crafting.
      * - Waits for the specified crafting duration plus random variance.
      *
+     * Usage example:
+     *
+     * ```
+     * val params = StandingTaskParams(...)
+     * orchestrator.processAtBank(params)
+     * ```
+     *
      * @param taskParams The [StandingTaskParams] configuring the task details like bank location, hotkeys, and durations.
      */
     override fun processAtBank(
@@ -204,6 +279,12 @@ private class RSAgent(override val automaton: Automaton = RobotController()) : R
      *
      * - Waits for the randomized crafting duration.
      *
+     * Usage example:
+     * ```
+     * val params = TravelTaskParams(...)
+     * orchestrator.processAtStationNearBank(params)
+     * ```
+     *
      * @param taskParams The [TravelTaskParams] configuring the task details.
      */
     override fun processAtStationNearBank(
@@ -246,6 +327,15 @@ private class RSAgent(override val automaton: Automaton = RobotController()) : R
      *
      * The delay allows the mouse to settle before sampling its position.
      *
+     * Usage example:
+     * ```
+     * // Get bank location from user mouse position
+     * val bankPoint = orchestrator.getBankPoint()
+     * // Left click the bank to open the interface
+     * orchestrator.automaton.mouseMove(bankPoint)
+     * orchestrator.automaton.mouseClick(InputEvent.BUTTON1_DOWN_MASK)
+     * ```
+     *
      * @return The Point position of the mouse after user positions it.
      */
     override fun getBankPoint(): Point {
@@ -261,6 +351,12 @@ private class RSAgent(override val automaton: Automaton = RobotController()) : R
      *
      * A random variance is also added to the sleep duration to add some less-robotic behavior.
      *
+     * Usage example:
+     * ```
+     * val ticks = 10 // Sleep for 10 game ticks
+     * orchestrator.sleepTicks(ticks)
+     * ```
+     *
      * @param n The number of game ticks to sleep for.
      */
     fun sleepForNTicks(n: Long) {