(#87) Screen API docs

Author: s1hofmann

Diff for: lib/screen.class.ts

@@ -11,34 +11,68 @@ import { timeout } from "./util/poll-action.function";
 
 export type FindHookCallback = (target: MatchResult) => Promise<void>;
 
+/**
+ * {@link Screen} class provides methods to access screen content of a systems main display
+ */
 export class Screen {
+
+  /**
+   * Config object for {@link Screen} class
+   */
   public config = {
+    /**
+     * Configures the required matching percentage for template images to be declared as a match
+     */
     confidence: 0.99,
+
+    /**
+     * Configures the path from which template images are loaded from
+     */
     resourceDirectory: cwd(),
   };
 
+  /**
+   * {@link Screen} class constructor
+   * @param vision {@link VisionAdapter} instance which bundles access to screen and / or computer vision related APIs
+   * @param findHooks A {@link Map} of {@link FindHookCallback} methods assigned to a template image filename
+   */
   constructor(
     private vision: VisionAdapter,
     private findHooks: Map<string, FindHookCallback[]> = new Map<string, FindHookCallback[]>()) {
   }
 
+  /**
+   * {@link width} returns the main screen width
+   * This refers to the hardware resolution.
+   * Screens with higher pixel density (e.g. retina displays in MacBooks) might have a higher width in in actual pixels
+   */
   public width() {
     return this.vision.screenWidth();
   }
 
+  /**
+   * {@link height} returns the main screen height
+   * This refers to the hardware resolution.
+   * Screens with higher pixel density (e.g. retina displays in MacBooks) might have a higher height in in actual pixels
+   */
   public height() {
     return this.vision.screenHeight();
   }
 
+  /**
+   * {@link find} will search for a template image on a systems main screen
+   * @param templateImageFilename Filename of the template image, relative to {@link Screen.config.resourceDirectory}
+   * @param params {@link LocationParameters} which are used to fine tune search region and / or match confidence
+   */
   public async find(
-    pathToNeedle: string,
+    templateImageFilename: string,
     params?: LocationParameters,
   ): Promise<Region> {
     const minMatch = (params && params.confidence) || this.config.confidence;
     const searchRegion =
       (params && params.searchRegion) || await this.vision.screenSize();
 
-    const fullPathToNeedle = normalize(join(this.config.resourceDirectory, pathToNeedle));
+    const fullPathToNeedle = normalize(join(this.config.resourceDirectory, templateImageFilename));
 
     const screenImage = await this.vision.grabScreen();
 
@@ -53,39 +87,58 @@ export class Screen {
       try {
         const matchResult = await this.vision.findOnScreenRegion(matchRequest);
         if (matchResult.confidence >= minMatch) {
-          const possibleHooks = this.findHooks.get(pathToNeedle) || [];
+          const possibleHooks = this.findHooks.get(templateImageFilename) || [];
           for (const hook of possibleHooks) {
             await hook(matchResult);
           }
           resolve(matchResult.location);
         } else {
           reject(
-            `No match for ${pathToNeedle}. Required: ${minMatch}, given: ${
+            `No match for ${templateImageFilename}. Required: ${minMatch}, given: ${
               matchResult.confidence
               }`,
           );
         }
       } catch (e) {
         reject(
-          `Searching for ${pathToNeedle} failed. Reason: '${e}'`,
+          `Searching for ${templateImageFilename} failed. Reason: '${e}'`,
         );
       }
     });
   }
 
+  /**
+   * {@link waitFor} searches for a template image for a specified duration
+   * @param templateImageFilename Filename of the template image, relative to {@link Screen.config.resourceDirectory}
+   * @param timeoutMs Timeout in milliseconds after which {@link waitFor} fails
+   * @param params {@link LocationParameters} which are used to fine tune search region and / or match confidence
+   */
   public async waitFor(
-    pathToNeedle: string,
+    templateImageFilename: string,
     timeoutMs: number = 5000,
     params?: LocationParameters,
   ): Promise<Region> {
-    return timeout(500, timeoutMs, () => this.find(pathToNeedle, params));
+    return timeout(500, timeoutMs, () => this.find(templateImageFilename, params));
   }
 
-  public on(pathToNeedle: string, callback: FindHookCallback) {
-    const existingHooks = this.findHooks.get(pathToNeedle) || [];
-    this.findHooks.set(pathToNeedle, [...existingHooks, callback]);
+  /**
+   * {@link on} registeres a callback which is triggered once a certain template image is found
+   * @param templateImageFilename Template image to trigger the callback on
+   * @param callback The {@link FindHookCallback} function to trigger
+   */
+  public on(templateImageFilename: string, callback: FindHookCallback) {
+    const existingHooks = this.findHooks.get(templateImageFilename) || [];
+    this.findHooks.set(templateImageFilename, [...existingHooks, callback]);
   }
 
+  /**
+   * {@link capture} captures a screenshot of a systems main display
+   * @param fileName Basename for the generated screenshot
+   * @param fileFormat The {@link FileType} for the generated screenshot
+   * @param filePath The output path for the generated screenshot (Default: {@link cwd})
+   * @param fileNamePrefix Filename prefix for the generated screenshot (Default: empty)
+   * @param fileNamePostfix Filename postfix for the generated screenshot (Default: empty)
+   */
   public async capture(
     fileName: string,
     fileFormat: FileType = FileType.PNG,