From 514091856fb015f10162544e1aa7d2e0125b8834 Mon Sep 17 00:00:00 2001
From: Shane Osbourne <sosbourne@duckduckgo.com>
Date: Tue, 15 Aug 2023 17:16:57 +0100
Subject: [PATCH] added webCompat as a docs page

---
 src/features/web-compat.js | 59 ++++++++++++++++++++++++++++++--------
 typedoc.json               |  1 +
 2 files changed, 48 insertions(+), 12 deletions(-)

diff --git a/src/features/web-compat.js b/src/features/web-compat.js
index ecd4adc0e..bfbace0bd 100644
--- a/src/features/web-compat.js
+++ b/src/features/web-compat.js
@@ -1,20 +1,26 @@
-import ContentFeature from '../content-feature.js'
-
 /**
- * Fixes incorrect sizing value for outerHeight and outerWidth
+ * @module Web Compat
+ *
+ * @description
+ *
+ * A suite of individual 'fixes'
+ *
+ * - {@link default.windowSizingFix Window Sizing Fix}
+ * - {@link default.navigatorCredentialsFix Navigator Credentials Fix}
+ * - {@link default.safariObjectFix Safari Object Fix}
+ * - {@link default.notificationFix Notification Fix}
+ * - {@link default.messageHandlersFix Message Handlers Fix}
+ * - {@link default.notificationFix Notification Fix}
+ * - {@link default.permissionsFix Permissions Fix}
+ *
  */
-function windowSizingFix () {
-    if (window.outerHeight !== 0 && window.outerWidth !== 0) {
-        return
-    }
-    window.outerHeight = window.innerHeight
-    window.outerWidth = window.innerWidth
-}
+
+import ContentFeature from '../content-feature.js'
 
 export default class WebCompat extends ContentFeature {
     init () {
         if (this.getFeatureSettingEnabled('windowSizing')) {
-            windowSizingFix()
+            this.windowSizingFix()
         }
         if (this.getFeatureSettingEnabled('navigatorCredentials')) {
             this.navigatorCredentialsFix()
@@ -34,6 +40,17 @@ export default class WebCompat extends ContentFeature {
         }
     }
 
+    /**
+     * Fixes incorrect sizing value for outerHeight and outerWidth
+     */
+    windowSizingFix () {
+        if (window.outerHeight !== 0 && window.outerWidth !== 0) {
+            return
+        }
+        window.outerHeight = window.innerHeight
+        window.outerWidth = window.innerWidth
+    }
+
     /**
      * Notification fix for adding missing API for Android WebView.
      */
@@ -186,9 +203,27 @@ export default class WebCompat extends ContentFeature {
 
     /**
      * Support for proxying `window.webkit.messageHandlers`
+     *
+     * This was added to fix breakage in situations where sites
+     * see `window.webkit` and then assume their own handlers would be present.
+     *
+     * For example, it fixes when a site tries to do the following:
+     *
+     * ```javascript
+     * if (window.webkit) {
+     *    window.webkit.messageHandlers.myHandler.postMessage({})
+     *    //                            ^^^^^^^^^ when this is absent, postMessage throws
+     * }
+     * ```
+     *
+     * **Remote Config:**
+     *
+     * This feature needs to be configured to allow some known
+     * methods (ones we add) to pass though (using Reflect) whilst polyfilling others,
+     * see {@link "Webcompat Settings Schema".WebCompatSettings.messageHandlers}
      */
     messageHandlersFix () {
-        /** @type {import('../types//webcompat-settings').WebCompatSettings['messageHandlers']} */
+        /** @type {import('../types/webcompat-settings').WebCompatSettings['messageHandlers']} */
         const settings = this.getFeatureSetting('messageHandlers')
 
         // Do nothing if `messageHandlers` is absent
diff --git a/typedoc.json b/typedoc.json
index e786c414f..17bd80698 100644
--- a/typedoc.json
+++ b/typedoc.json
@@ -12,6 +12,7 @@
         "src/features/duckplayer/thumbnails.js",
         "src/features/duckplayer/video-overlay.js",
         "src/features/harmful-apis.js",
+        "src/features/web-compat.js",
         "packages/messaging",
         "packages/messaging/schema.js",
         "packages/messaging/native.js",