feat: add docstrings and doc files (#63)

Author: arjunattam

README.md

@@ -24,9 +24,12 @@ export default defineConfig({
       name: "android",
       use: {
         platform: Platform.ANDROID,
-        deviceName: "Google Pixel 8",
-        osVersion: "14.0",
-        buildURL: process.env.BROWSERSTACK_APP_URL,
+        device: {
+          provider: "emulator",
+          name: "Google Pixel 8",
+          osVersion: "14.0",
+        }
+        buildPath: "app-release.apk",
       },
     },
   ],
@@ -42,16 +45,7 @@ npx appwright test --project android
 npx appwright test --project ios
 ```
 
-These environment variables are required:
+## Docs
 
-- BROWSERSTACK_USERNAME
-- BROWSERSTACK_ACCESS_KEY
-- BROWSERSTACK_APP_URL
-
-## Development
-
-### Install dependencies
-
-```bash
-npm install
-```
+- [Configuration](docs/config.md)
+- [Locators](docs/locators.md)

docs/assertions.md

@@ -0,0 +1,2 @@
+- Assertions
+  - await expect().toBeVisible()

docs/basics.md

@@ -0,0 +1,4 @@
+- Basics
+  - Write a test: Built-in fixtures (client)
+  - Run the test
+    - See report

docs/config.md

@@ -0,0 +1,23 @@
+# Configuration
+
+- Configuration
+  - Choose which devices to test and device provider (local or BrowserStack)
+
+## Device Providers
+
+Device providers make Appium compatible mobile devices available to Appwright. These
+providers are supported:
+
+- `local-device`
+- `emulator`
+- `browserstack`
+
+### BrowserStack
+
+BrowserStack [App Automate](https://www.browserstack.com/app-automate) can be used to provide
+remote devices to Appwright.
+
+These environment variables are required for the BrowserStack
+
+- BROWSERSTACK_USERNAME
+- BROWSERSTACK_ACCESS_KEY

docs/locators.md

@@ -0,0 +1,4 @@
+- Locators
+  - How to select an element
+    - These actions are on `client`
+  - How to take actions on the element

docs/reference.md

@@ -0,0 +1,3 @@
+- API reference
+  - Driver -> get locators
+  - Locator -> actions

src/types/index.ts

@@ -37,35 +37,80 @@ export enum Platform {
 }
 
 export interface IDevice {
+  /**
+   * Helper method to identify which the mobile OS running on the device.
+   * @returns "android" or "ios"
+   */
+  getPlatform: () => Platform;
+
+  /**
+   * Closes the automation session. This is called automatically after each test.
+   */
   close: () => Promise<void>;
 
+  /**
+   * Tap on the screen at the given coordinates, specified as x and y. The top left corner
+   * of the screen is { x: 0, y: 0 }.
+   *
+   * @param coordinates to tap on
+   * @returns
+   */
   tap: ({ x, y }: { x: number; y: number }) => Promise<void>;
 
+  /**
+   * Locate an element on the screen with text content. This method defaults to a
+   * substring match, and this be overridden by setting the `exact` option to `true`.
+   *
+   * **Usage:**
+   * ```js
+   * // with string
+   * const submitButton = device.getByText("Submit");
+   *
+   * // with RegExp
+   * const counter = device.getByText(/^Counter: \d+/);
+   * ```
+   *
+   * @param text string or regular expression to search for
+   * @param options
+   * @returns
+   */
   getByText: (
     text: string | RegExp,
     options?: { exact?: boolean },
   ) => AppwrightLocator;
 
+  /**
+   * Locate an element on the screen with accessibility identifier. This method defaults to
+   * a substring match, and this can be overridden by setting the `exact` option to `true`.
+   *
+   * @param text string or regular expression to search for
+   * @param options
+   * @returns
+   */
   getById: (
     text: string | RegExp,
     options?: { exact?: boolean },
   ) => AppwrightLocator;
 
   getByXpath: (xpath: string) => AppwrightLocator;
 
+  /**
+   * Retrieves text content from the clipboard of the mobile device. This is useful
+   * after a "copy to clipboard" action has been performed.
+   *
+   * @returns Returns the text content of the clipboard.
+   */
   getClipboardText: () => Promise<string>;
 
   beta: {
     tap: (prompt: string) => Promise<void>;
     extractText: (prompt: string) => Promise<string>;
   };
-
-  getPlatform: () => Platform;
 }
 
 export interface AppwrightLocator {
   /**
-   * Clicks (taps) on the element. This method waits for the element to be visible before clicking it.
+   * Taps (clicks) on the element. This method waits for the element to be visible before clicking it.
    *
    * **Usage:**
    * ```js