Routines has usage examples

src/main/kotlin/Routines.kt

@@ -2,17 +2,29 @@ import java.awt.Point
 import java.awt.event.KeyEvent
 
 /**
- * Routines contains utility functions to perform common bot tasks and workflows.
+ * Routines object containing reusable workflows for common scripts.
  *
- * This includes functions like:
+ * This object encapsulates reusable routines for common botting workflows.
- * - fullRunIncense: Handles the full incense stick crafting workflow.
+ * It provides an easy way to invoke these flows without having to reimplement
- * - processInventoryAtFurnace: Processes a total volume of inventory at a furnace near the bank.
+ * the lower-level actions each time.
- * - processRefinedPlanksIntoFrames:Processes refined planks into frames at a sawmill near the bank.
  *
- * The routines use an Agent instance to perform actions like banking,
+ * The routines are structured as standalone methods that accept the necessary
- * depositing items, withdrawing presets, etc.
+ * parameters. This allows them to be called independently and composed in
+ * different combinations.
  *
- * The routines are encapsulated for pure convenience
+ * For example, the fullRunIncense routine orchestrates the entire incense
+ * stick crafting workflow by invoking the individual steps:
+ *
+ * - cleanHerbs
+ * - cutIncenseSticks
+ * - coatIncenseSticks
+ * - infuseIncenseSticks
+ *
+ * The individual steps can also be called independently as needed.
+ *
+ * This structure makes the routines reusable, customizable, and composable.
+ * Scripts can invoke the routines directly rather than reimplementing the
+ * underlying actions. Parameters allow customizing volumes, locations etc.
  */
 object Routines {
     /**
@@ -40,7 +52,18 @@ object Routines {
      * - Infusing clean herbs into sticks
      *
      * It loops through each step based on the provided volumes, performing the
-     * actions at the bank. The bank location is prompted from the user.
+     * actions at the bank.
+     *
+     * Usage example:
+     *
+     * ```
+     * val herbs = 1000
+     * val logs = 2000
+     * val ashes = 1500
+     * val cleanHerbs = herbs + 150
+     *
+     * Routines.fullRunIncense(herbs, logs, ashes, cleanHerbs)
+     * ```
      *
      * Progress is printed after each step. Total elapsed time is printed at the end.
      */
@@ -97,6 +120,18 @@ object Routines {
      * - Depositing clean herbs
      *
      * It performs the actions at the bank location using the provided agent.
+     *
+     * Usage examples:
+     * ```
+     * val volume = 1000
+     * val bankPoint = Point(100, 200)
+     * val agent = RSAgent.getInstance()
+     * Routines.cleanHerbs(volume, agent, bankPoint)
+     * ```
+     * Can also omit agent and bankPoint to use defaults:
+     * ```
+     * Routines.cleanHerbs(1000)
+     * ```
      */
     fun cleanHerbs(volume: Int, agent: RSOrchestrator = RSOrchestrator.getInstance(), bankPoint: Point = agent.getBankPoint()) {
         val params = StandingTaskParams(
@@ -123,6 +158,19 @@ object Routines {
      * - Withdrawing magic log preset
      * - Cutting magic logs into incense sticks without dialog
      * - Depositing incense sticks
+     *
+     * Usage examples:
+     * ```
+     * val logs = 1000
+     * val bankPoint = Point(100, 200)
+     * val agent = RSAgent.getInstance()
+     *
+     * Routines.cutIncenseSticks(logs, agent, bankPoint)
+     * ```
+     * Can also omit agent and bankPoint to use defaults:
+     * ```
+     * Routines.cutIncenseSticks(1000)
+     * ```
      */
     fun cutIncenseSticks(volume: Int, agent: RSOrchestrator = RSOrchestrator.getInstance(), bankPoint: Point = agent.getBankPoint()) {
         val params = StandingTaskParams(
@@ -149,6 +197,20 @@ object Routines {
      * - Withdrawing incense stick preset
      * - Coating incense sticks with ashes using hotkey
      * - Depositing coated sticks
+     *
+     * Usage examples:
+     * ```
+     * val sticks = 1000
+     * val bankPoint = Point(100, 200)
+     * val agent = RSAgent.getInstance()
+     *
+     * Routines.coatIncenseSticks(sticks, agent, bankPoint)
+     * ```
+     * Can also omit agent and bankPoint to use defaults:
+     *
+     * ```
+     * Routines.coatIncenseSticks(1000)
+     * ```
      */
     fun coatIncenseSticks(volume: Int, agent: RSOrchestrator = RSOrchestrator.getInstance(), bankPoint: Point = agent.getBankPoint()) {
         val params = StandingTaskParams(
@@ -174,6 +236,19 @@ object Routines {
      * - Withdrawing incense stick preset
      * - Infusing incense sticks with herbs using hotkey
      * - Depositing infused incense sticks
+     *
+     *  Usage examples:
+     *  ```
+     *  val sticks = 1000
+     *  val bankPoint = Point(100, 200)
+     *  val agent = RSAgent.getInstance()
+     *
+     *  Routines.infuseIncenseSticks(sticks, agent, bankPoint)
+     *  ```
+     *  Can also omit agent and bankPoint to use defaults:
+     *  ```
+     *  Routines.infuseIncenseSticks(1000)
+     *  ```
      */
     fun infuseIncenseSticks(volume: Int, agent: RSOrchestrator = RSOrchestrator.getInstance(), bankPoint: Point = agent.getBankPoint()) {
         val params = StandingTaskParams(
@@ -201,6 +276,14 @@ object Routines {
      * - The volume, volume per trip, bank point, crafting hotkey, and other details
      * - It calls the orchestrator's doStandingTask() method to execute the task.
      *
+     * Usage example:
+     * ```
+     * val volume = 1000
+     * val bankPoint = Point(100, 200)
+     * val agent = RSAgent.getInstance()
+     * Routines.craftPotionsAtBank(volume, agent, bankPoint)
+     * ```
+     *
      * Progress is automatically printed during execution.
      *
      * @deprecated This method needs validation before use in production.
@@ -236,6 +319,15 @@ object Routines {
      *
      * It calls the orchestrator's doTravelTask() method to execute the grinding task.
      *
+     *  Usage example:
+     *  ```
+     *  val volume = 1000
+     *  val travelDuration = 5000 // 5 seconds
+     *  val bankPoint = Point(100, 200)
+     *  val wellPoint = Point(300, 400) // Prompted from user
+     *  Routines.potionGrindWithWell(volume, travelDuration, bankPoint, wellPoint)
+     *  ```
+     *
      * Progress is automatically printed during execution.
      *
      * @deprecated This method needs validation before use in production.
@@ -282,6 +374,17 @@ object Routines {
      * The furnace and bank locations are passed in as specific Point locations.
      * The agent handles the navigation and banking actions.
      *
+     *  Usage example:
+     *
+     *  ```
+     *  val volume = 28
+     *  val bankPoint = Point(100, 200)
+     *  val furnacePoint = Point(300, 400)
+     *  val agent = RSAgent.getInstance()
+     *
+     *  Routines.processAtFurnaceNearBank(volume, agent, bankPoint, furnacePoint)
+     *  ```
+     *
      * Before processing, the camera is reset to align points.
      */
     fun processInventoryAtFurnace(volume: Int) {