it's nice when important code is commented

www/bounce/main.js

@@ -1,27 +1,46 @@
 define(['/api/config'], function (ApiConfig) {
+/*  The 'bounce app' provides a unified way to do the following things in CryptPad
+
+    1. remove the 'opener' attribute from the tab/window every time you navigate
+    2. detect and block malicious URLs after warning the user
+    3. inform users when they are navigating away from their cryptpad instance
+
+*/
+
+    // when a URL is rejected we close the window
     var reject = function () {
         window.close();
     };
+    // this app is intended to be loaded and used exclusively from the sandbox domain
+    // where stricter CSP blocks various attacks. Reject any other usage.
     if (ApiConfig.httpSafeOrigin !== window.location.origin) {
         window.alert('The bounce application must only be used from the sandbox domain, ' +
             'please report this issue on https://github.com/xwiki-labs/cryptpad');
-        return;
+        return void reject();
     }
+    // Old/bad browsers lack the URL API, making it more difficult to validate and compare URLs.
+    // Warn and reject.
     if (typeof(URL) !== 'function') {
         window.alert("Your browser does not support functionality this page requires");
         return void reject();
     }
 
+    // remove the 'opener' to prevent 'reverse tabnabbing'.
     window.opener = null;
 
+    // Parse the outer domain's root URL to facilitate comparisons.
+    // Reject everything if this fails to parse.
     var host;
     try {
         host = new URL('', ApiConfig.httpUnsafeOrigin);
     } catch (err) {
-        window.alert("This server is configured incorrectly. Its administrator should check its diagnostics page");
+        window.alert("This server is configured incorrectly. Details for its administrator can be found on its diagnostics page.");
         return void reject();
     }
 
+    // Decode the target URL that should have been provided through the document's hash.
+    // Reject if no URL was provided.
+    // Absolute URLs are easy to handle, other consider URLs relative to the outer domain.
     var target;
     try {
         var bounceTo = decodeURIComponent(window.location.hash.slice(1));
@@ -32,21 +51,29 @@ define(['/api/config'], function (ApiConfig) {
         return void reject();
     }
 
+    // Valid links should navigate to the normalized href
     var go = function () {
         window.location.href = target.href;
     };
 
+    // Local URLs don't require any warning and can navigate directly without user input.
     if (target.host === host.host) { return void go(); }
 
+    // Everything else requires user input, so we load the platform's translations.
+    // FIXME: this seems to infer language preferences from the browser instead of the user's account preferences
     require([
         '/customize/messages.js',
     ], function (Messages) {
+        // The provided URL seems to be a malicious or invalid payload.
+        // Inform the user that we won't navigate and that the 'bounce tab' will be closed.
         if (['javascript:', 'vbscript:', 'data:', 'blob:'].includes(target.protocol)) {
             window.alert(Messages._getKey('bounce_danger', [target.href]));
             return void reject();
         }
 
+        // The provided URL will navigate the user away from the outer domain.
         var question = Messages._getKey('bounce_confirm', [host.hostname, target.href]);
+        // Confirm that they want to leave, then navigate or reject based on their choice.
         var answer = window.confirm(question);
         if (answer) { return void go(); }
         reject();