Umutayb · Apr 5, 2026 · Apr 5, 2026 · Apr 5, 2026
diff --git a/README.md b/README.md
@@ -425,45 +425,48 @@ Supported platform values: `web` | `android` | `ios` | `macos` | `windows`
 ## 🏛️ Architecture
 
 ```
-┌─────────────────────────────────────────────────────┐
-│                  Your Test Project                  │
-│  ┌──────────┐   ┌──────────┐  ┌───────────────────┐ │
-│  │ Feature  │   │  Hooks   │  │  Page Objects     │ │
-│  │  Files   │   │          │  │  (Java or JSON)   │ │
-│  │(.feature)│   │(@Before/ │  │                   │ │
-│  │          │   │ @After)  │  │                   │ │
-│  └────┬─────┘   └────┬─────┘  └────────┬──────────┘ │
-└───────┼──────────────┼─────────────────┼────────────┘
-        │              │                 │
-┌───────┼──────────────┼─────────────────┼────────────┐
-│       ▼              ▼                 ▼   Pickleib │
-│  ┌──────────┐  ┌──────────┐  ┌───────────────────┐  │
-│  │BuiltIn   │  │Pickleib  │  │ PageObjectRegistry│  │
-│  │Steps     │  │WebDriver │  │ or PageObjectJson │  │
-│  │(68 steps)│  │(ThreadL) │  │(ElementRepository)│  │
-│  └────┬─────┘  └──────────┘  └────────┬──────────┘  │
-│       │                               │             │
-│       ▼                               ▼             │
-│  ┌──────────────────────────────────────────────┐   │
-│  │           InteractionBase                    │   │
-│  │    ┌───────────────┐  ┌────────────────┐     │   │
-│  │    │WebInteractions│  │PlatformInteract│     │   │
-│  │    │  (Selenium)   │  │    (Appium)    │     │   │
-│  │    └──────┬────────┘  └───────┬────────┘     │   │
-│  └───────────┼───────────────────┼──────────────┘   │
-│              │                   │                  │
-│  ┌───────────▼───────────────────▼──────────────┐   │
-│  │              Utility Helpers                 │   │
-│  │  ┌─────────┐ ┌──────────┐ ┌───────────────┐  │   │
-│  │  │ClickHlp │ │InputHelp │ │ElementStateHlp│  │   │
-│  │  └────┬────┘ └────┬─────┘ └───────┬───────┘  │   │
-│  └───────┼───────────┼───────────────┼──────────┘   │
-│          └───────────┼───────────────┘              │
-│                      ▼                              │
-│              ┌──────────────┐                       │
-│              │  RetryPolicy │                       │
-│              └──────────────┘                       │
-└─────────────────────────────────────────────────────┘
+┌────────────────────────────────────────────────────────────────────┐
+│                         Your Test Project                          │
+│                                                                    │
+│  ┌──────────┐   ┌──────────┐  ┌───────────────┐   ┌─────────────┐  │
+│  │ Feature  │   │  Hooks   │  │ Page Objects  │   │ Test Runner │  │
+│  │  Files   │   │          │  │(Java or JSON) │   │             │  │
+│  │(.feature)│   │(@Before/ │  │               │   │ (@Pickleib/ │  │
+│  │          │   │ @After)  │  │               │   │  @CukeOpts) │  │
+│  └────┬─────┘   └────┬─────┘  └───────┬───────┘   └──────┬──────┘  │
+│       │              │                │                  │         │
+└───────┼──────────────┼────────────────┼──────────────────┼─────────┘
+        │              │                │                  │
+┌───────┼──────────────┼────────────────┼──────────────────┼─────────┐
+│       ▼              ▼                ▼                  ▼         │
+│                                                           Pickleib │
+│   ┌──────────┐  ┌──────────┐  ┌───────────────────┐  ┌─────────┐   │
+│   │BuiltIn   │  │Pickleib  │  │ PageObjectRegistry│  │Pickleib │   │
+│   │Steps     │  │WebDriver │  │ or PageObjectJson │  │Runner   │   │
+│   │(68 steps)│  │(ThreadL) │  │(ElementRepository)│  │(ExtendW)│   │
+│   └────┬─────┘  └──────────┘  └────────┬──────────┘  └─────────┘   │
+│        │                               │                           │
+│        ▼                               ▼                           │
+│   ┌──────────────────────────────────────────────────────────┐     │
+│   │                    InteractionBase                       │     │
+│   │    ┌───────────────┐          ┌────────────────┐         │     │
+│   │    │WebInteractions│          │PlatformInteract│         │     │
+│   │    │  (Selenium)   │          │    (Appium)    │         │     │
+│   │    └──────┬────────┘          └───────┬────────┘         │     │
+│   └───────────┼───────────────────────────┼──────────────────┘     │
+│               │                           │                        │
+│   ┌───────────▼───────────────────────────▼──────────────────┐     │
+│   │                    Utility Helpers                       │     │
+│   │  ┌─────────┐    ┌──────────┐    ┌───────────────┐        │     │
+│   │  │ClickHlp │    │InputHelp │    │ElementStateHlp│        │     │
+│   │  └────┬────┘    └────┬─────┘    └───────┬───────┘        │     │
+│   └───────┼──────────────┼──────────────────┼────────────────┘     │
+│           └──────────────┼──────────────────┘                      │
+│                          ▼                                         │
+│                   ┌──────────────┐                                 │
+│                   │  RetryPolicy │                                 │
+│                   └──────────────┘                                 │
+└────────────────────────────────────────────────────────────────────┘
 ```
 
 ---

diff --git a/src/main/java/pickleib/annotations/ContextValue.java b/src/main/java/pickleib/annotations/ContextValue.java
@@ -5,9 +5,15 @@
 import java.lang.annotation.RetentionPolicy;
 import java.lang.annotation.Target;
 
+/**
+ * Injects a value from the {@link context.ContextStore} into the annotated field.
+ * Supports {@code {{key}}} replacement patterns.
+ */
 @Retention(RetentionPolicy.RUNTIME)
 @Target({ElementType.FIELD, ElementType.PARAMETER})
 public @interface ContextValue {
+    /** @return the context key to look up */
     String value();
+    /** @return the fallback value if the key is not found */
     String defaultValue() default "";
 }
diff --git a/src/main/java/pickleib/annotations/PageObject.java b/src/main/java/pickleib/annotations/PageObject.java
@@ -6,9 +6,12 @@
 import java.lang.annotation.RetentionPolicy;
 import java.lang.annotation.Target;
 
+/** Marks a class as a page object for automatic registration by {@link pickleib.runner.PickleibRunner}. */
 @Retention(RetentionPolicy.RUNTIME)
 @Target(ElementType.TYPE)
 public @interface PageObject {
+    /** @return the target platform for this page object */
     Platform platform() default Platform.web;
+    /** @return custom registry name (defaults to class name) */
     String name() default "";
 }
diff --git a/src/main/java/pickleib/annotations/Pickleib.java b/src/main/java/pickleib/annotations/Pickleib.java
@@ -5,10 +5,14 @@
 import java.lang.annotation.RetentionPolicy;
 import java.lang.annotation.Target;
 
+/** Marks a test runner class for automatic Pickleib element repository setup. */
 @Retention(RetentionPolicy.RUNTIME)
 @Target(ElementType.TYPE)
 public @interface Pickleib {
+    /** @return packages to scan for {@code @PageObject} / {@code @ScreenObject} classes */
     String[] scan() default {};
+    /** @return whether to enable built-in Cucumber step definitions */
     boolean builtInSteps() default true;
+    /** @return path to the {@code page-repository.json} file */
     String pageRepository() default "";
 }
diff --git a/src/main/java/pickleib/annotations/ScreenObject.java b/src/main/java/pickleib/annotations/ScreenObject.java
@@ -6,9 +6,12 @@
 import java.lang.annotation.RetentionPolicy;
 import java.lang.annotation.Target;
 
+/** Marks a class as a mobile screen object for automatic registration. */
 @Retention(RetentionPolicy.RUNTIME)
 @Target(ElementType.TYPE)
 public @interface ScreenObject {
+    /** @return the target platform for this screen object */
     Platform platform() default Platform.android;
+    /** @return custom registry name (defaults to class name) */
     String name() default "";
 }
diff --git a/src/main/java/pickleib/annotations/StepDefinitions.java b/src/main/java/pickleib/annotations/StepDefinitions.java
@@ -5,6 +5,7 @@
 import java.lang.annotation.RetentionPolicy;
 import java.lang.annotation.Target;
 
+/** Marks a class as containing Cucumber step definitions. */
 @Retention(RetentionPolicy.RUNTIME)
 @Target(ElementType.TYPE)
 public @interface StepDefinitions {

diff --git a/src/main/java/pickleib/driver/DriverFactory.java b/src/main/java/pickleib/driver/DriverFactory.java
@@ -20,7 +20,9 @@ public interface DriverFactory {
      * </ul>
      */
     enum DriverType {
+        /** Selenium WebDriver for web browser automation. */
         selenium,
+        /** Appium driver for mobile/desktop automation. */
         appium;
 
         /**

diff --git a/src/main/java/pickleib/enums/Direction.java b/src/main/java/pickleib/enums/Direction.java
@@ -3,12 +3,16 @@
 import lombok.Getter;
 
 /**
- * Basic direction
+ * Basic scroll/swipe direction.
  */
 @Getter
 public enum Direction {
+    /** Scroll upward. */
     up,
+    /** Scroll downward. */
     down,
+    /** Scroll left. */
     left,
+    /** Scroll right. */
     right
 }
diff --git a/src/main/java/pickleib/enums/ElementState.java b/src/main/java/pickleib/enums/ElementState.java
@@ -3,14 +3,20 @@
 import lombok.Getter;
 
 /**
- * Element states
+ * Expected states for element verification.
  */
 @Getter
 public enum ElementState {
+    /** Element is enabled for interaction. */
     enabled,
+    /** Element is visible on the page. */
     displayed,
+    /** Element is selected (e.g. checkbox). */
     selected,
+    /** Element is disabled. */
     disabled,
+    /** Element is not selected. */
     unselected,
+    /** Element is not present in the DOM. */
     absent
 }
diff --git a/src/main/java/pickleib/enums/EmulatedDevice.java b/src/main/java/pickleib/enums/EmulatedDevice.java
@@ -3,62 +3,117 @@
 import lombok.Getter;
 import java.util.Map;
 
+/** Chrome DevTools emulated device profiles for mobile testing. */
 @Getter
 public enum EmulatedDevice {
 
+    /** iPad Air device profile. */
     iPadAir("iPad Air"),
+    /** iPhone 4 device profile. */
     iPhone4("iPhone 4"),
+    /** iPhone 5/SE device profile. */
     iPhone5SE("iPhone 5/SE"),
+    /** iPhone 6 device profile. */
     iPhone6("iPhone 6"),
+    /** iPhone 7 device profile. */
     iPhone7("iPhone 7"),
+    /** iPhone 8 device profile. */
     iPhone8("iPhone 8"),
+    /** iPhone 6 Plus device profile. */
     iPhone6Plus("iPhone 6 Plus"),
+    /** iPhone 7 Plus device profile. */
     iPhone7Plus("iPhone 7 Plus"),
+    /** iPhone 8 Plus device profile. */
     iPhone8Plus("iPhone 8 Plus"),
+    /** iPhone X device profile. */
     iPhoneX("iPhone X"),
+    /** iPhone 12 Pro device profile. */
     iPhone12Pro("iPhone 12 Pro"),
+    /** Nexus 4 device profile. */
     Nexus4("Nexus 4"),
+    /** Nexus 5 device profile. */
     Nexus5("Nexus 5"),
+    /** Nexus 5X device profile. */
     Nexus5X("Nexus 5X"),
+    /** Nexus 6 device profile. */
     Nexus6("Nexus 6"),
+    /** Nexus 6P device profile. */
     Nexus6P("Nexus 6P"),
+    /** Nexus 7 device profile. */
     Nexus7("Nexus 7"),
+    /** Pixel 2 device profile. */
     Pixel2("Pixel 2"),
+    /** Pixel 2 XL device profile. */
     Pixel2XL("Pixel 2 XL"),
+    /** Microsoft Lumia 550 device profile. */
     MicrosoftLumia550("Microsoft Lumia 550"),
+    /** Microsoft Lumia 950 device profile. */
     MicrosoftLumia950("Microsoft Lumia 950"),
+    /** Galaxy S III device profile. */
     GalaxySIII("Galaxy S III"),
+    /** Galaxy S5 device profile. */
     GalaxyS5("Galaxy S5"),
+    /** Kindle Fire HDX device profile. */
     KindleFireHDX("Kindle Fire HDX"),
+    /** iPad Mini device profile. */
     iPadMini("iPad Mini"),
+    /** iPad device profile. */
     iPad("iPad"),
+    /** iPad Pro device profile. */
     iPadPro("iPad Pro"),
+    /** Nexus 10 device profile. */
     Nexus10("Nexus 10"),
+    /** Galaxy Note 3 device profile. */
     GalaxyNote3("Galaxy Note 3"),
+    /** Galaxy Note II device profile. */
     GalaxyNoteII("Galaxy Note II"),
+    /** Apple iPhone 4 device profile. */
     AppleiPhone4("Apple iPhone 4"),
+    /** Apple iPhone 5 device profile. */
     AppleiPhone5("Apple iPhone 5"),
+    /** Apple iPhone 6 device profile. */
     AppleiPhone6("Apple iPhone 6"),
+    /** BlackBerry Z30 device profile. */
     BlackBerryZ30("BlackBerry Z30"),
+    /** Google Nexus 4 device profile. */
     GoogleNexus4("Google Nexus 4"),
+    /** Google Nexus 5 device profile. */
     GoogleNexus5("Google Nexus 5"),
+    /** Google Nexus 6 device profile. */
     GoogleNexus6("Google Nexus 6"),
+    /** Google Nexus 7 device profile. */
     GoogleNexus7("Google Nexus 7"),
+    /** Google Nexus 10 device profile. */
     GoogleNexus10("Google Nexus 10"),
+    /** LG Optimus L70 device profile. */
     LGOptimusL70("LG Optimus L70"),
+    /** Nokia N9 device profile. */
     NokiaN9("Nokia N9"),
+    /** Nokia Lumia 520 device profile. */
     NokiaLumia520("Nokia Lumia 520"),
+    /** Samsung Galaxy S III device profile. */
     SamsungGalaxySIII("Samsung Galaxy S III"),
+    /** Samsung Galaxy S4 device profile. */
     SamsungGalaxyS4("Samsung Galaxy S4"),
+    /** Samsung Galaxy S20 Ultra device profile. */
     SamsungGalaxyS20Ultra("Samsung Galaxy S20 Ultra"),
+    /** Amazon Kindle Fire HDX device profile. */
     AmazonKindleFireHDX("Amazon Kindle Fire HDX"),
+    /** Apple iPad Mini device profile. */
     AppleiPadMini("Apple iPad Mini"),
+    /** Apple iPad device profile. */
     AppleiPad("Apple iPad"),
+    /** BlackBerry PlayBook device profile. */
     BlackBerryPlayBook("BlackBerry PlayBook"),
+    /** Samsung Galaxy Note 3 device profile. */
     SamsungGalaxyNote3("Samsung Galaxy Note 3"),
+    /** Samsung Galaxy Note II device profile. */
     SamsungGalaxyNoteII("Samsung Galaxy Note II"),
+    /** Laptop with touch device profile. */
     Laptopwithtouch("Laptop with touch"),
+    /** Laptop with HiDPI screen device profile. */
     LaptopwithHiDPIscreen("Laptop with HiDPI screen"),
+    /** Laptop with MDPI screen device profile. */
     LaptopwithMDPIscreen("Laptop with MDPI screen");
 
     final String deviceName;
@@ -67,10 +122,15 @@ public enum EmulatedDevice {
         this.deviceName = deviceName;
     };
 
+    /** @return a map containing the device name for Chrome mobile emulation */
     public Map<String, String> emulate(){
         return Map.of("deviceName", this.deviceName);
     }
 
+    /**
+     * @param text the device name to look up (case-insensitive)
+     * @return the matching {@link EmulatedDevice}, or {@code null} if not found
+     */
     public static EmulatedDevice getType(String text) {
         if (text != null)
             for (EmulatedDevice driverType:values())

diff --git a/src/main/java/pickleib/enums/InteractionType.java b/src/main/java/pickleib/enums/InteractionType.java
@@ -6,8 +6,12 @@
  * The available interaction types are click, fill, center, and verify.
  */
 public enum InteractionType {
+    /** Click on the element. */
     click,
+    /** Fill the element with input. */
     fill,
+    /** Scroll the element to center. */
     center,
+    /** Verify the element state. */
     verify
 }
diff --git a/src/main/java/pickleib/enums/Navigation.java b/src/main/java/pickleib/enums/Navigation.java
@@ -7,6 +7,8 @@
  */
 @Getter
 public enum Navigation {
+    /** Navigate backwards in browser history. */
     backwards,
+    /** Navigate forwards in browser history. */
     forwards
 }
diff --git a/src/main/java/pickleib/enums/Platform.java b/src/main/java/pickleib/enums/Platform.java
@@ -1,9 +1,15 @@
 package pickleib.enums;
 
+/** Supported automation platforms. */
 public enum Platform {
+    /** Web browser automation. */
     web,
+    /** Android mobile automation. */
     android,
+    /** iOS mobile automation. */
     ios,
+    /** macOS desktop automation. */
     macos,
+    /** Windows desktop automation. */
     windows
 }
diff --git a/src/main/java/pickleib/enums/PrimarySelectorType.java b/src/main/java/pickleib/enums/PrimarySelectorType.java
@@ -4,6 +4,8 @@
  * Defines primary selector types
  */
 public enum PrimarySelectorType {
+    /** CSS selector. */
     css,
+    /** XPath selector. */
     xpath
 }
diff --git a/src/main/java/pickleib/exceptions/PickleibException.java b/src/main/java/pickleib/exceptions/PickleibException.java
@@ -1,8 +1,11 @@
 package pickleib.exceptions;
 
+/** Runtime exception thrown by Pickleib when an interaction or verification fails. */
 public class PickleibException extends RuntimeException {
 
+    /** @param errorMessage the error message */
     public PickleibException(String errorMessage) {super(errorMessage);}
+    /** @param errorMessage the cause exception */
     public PickleibException(Exception errorMessage) {super(errorMessage);}
 
 }