From bff4a12fcb446250d739bb8416a4e2e4a8fbe030 Mon Sep 17 00:00:00 2001
From: Ethan Dalool <git@voussoir.net>
Date: Thu, 3 Sep 2020 11:46:26 -0700
Subject: [PATCH] Add various comments, docstrings, and console.log.

---
 frontends/etiquette_flask/static/js/common.js  |  5 +++++
 .../static/js/photo_clipboard.js               |  7 +++++--
 .../etiquette_flask/templates/clipboard.html   | 18 ++++++++++++++++++
 .../templates/clipboard_tray.html              |  5 ++++-
 4 files changed, 32 insertions(+), 3 deletions(-)

diff --git a/frontends/etiquette_flask/static/js/common.js b/frontends/etiquette_flask/static/js/common.js
index cbe96a9..7bd9efc 100644
--- a/frontends/etiquette_flask/static/js/common.js
+++ b/frontends/etiquette_flask/static/js/common.js
@@ -307,6 +307,11 @@ function init_button_with_confirm()
 common.init_enable_on_pageload =
 function init_enable_on_pageload()
 {
+    /*
+    To create an input element which is disabled at first, and is enabled when
+    the DOM has completed loading, give it the disabled attribute and the
+    class "enable_on_pageload".
+    */
     var elements = Array.from(document.getElementsByClassName("enable_on_pageload"));
     elements.forEach(function(element)
     {
diff --git a/frontends/etiquette_flask/static/js/photo_clipboard.js b/frontends/etiquette_flask/static/js/photo_clipboard.js
index 5148b09..4c7753a 100644
--- a/frontends/etiquette_flask/static/js/photo_clipboard.js
+++ b/frontends/etiquette_flask/static/js/photo_clipboard.js
@@ -16,7 +16,7 @@ function clear_clipboard()
 photo_clipboard.load_clipboard =
 function load_clipboard(event)
 {
-    console.log("Loading photo clipboard.");
+    console.log("Loading photo clipboard from localstorage.");
     var stored = localStorage.getItem("photo_clipboard");
     if (stored === null)
     {
@@ -41,7 +41,7 @@ function load_clipboard(event)
 photo_clipboard.save_clipboard =
 function save_clipboard()
 {
-    console.log("Saving photo clipboard.");
+    console.log("Saving photo clipboard to localstorage.");
     var serialized = JSON.stringify(Array.from(photo_clipboard.clipboard));
     localStorage.setItem("photo_clipboard", serialized);
     photo_clipboard.update_pagestate();
@@ -312,6 +312,9 @@ function on_storage_event()
 photo_clipboard.update_pagestate =
 function update_pagestate()
 {
+    /*
+    Update all relevant DOM elements to match internal state.
+    */
     photo_clipboard.update_clipboard_count();
     photo_clipboard.update_clipboard_tray();
     photo_clipboard.apply_check_all();
diff --git a/frontends/etiquette_flask/templates/clipboard.html b/frontends/etiquette_flask/templates/clipboard.html
index 1a8f8a3..fe61c71 100644
--- a/frontends/etiquette_flask/templates/clipboard.html
+++ b/frontends/etiquette_flask/templates/clipboard.html
@@ -154,6 +154,15 @@ common.bind_box_to_button(remove_box, remove_button);
 
 function recalculate_needed()
 {
+    /*
+    Populate the global `needed` set with all photo ids which are on the
+    clipboard but not on the page yet. When this page is first loaded, that
+    will be all ids. If the user adds more photos to their clipboard in a
+    different tab and returns to this tab, then the new ids will be needed.
+
+    This function only calculates which ids are needed. The actual fetching of
+    divs is in `request_more_divs`.
+    */
     needed = new Set();
     photo_clipboard.clipboard.forEach(function(photo_id)
     {
@@ -166,6 +175,10 @@ function recalculate_needed()
 
 function refresh_divs()
 {
+    /*
+    Add new divs to the page, and remove divs which the user has removed from
+    their clipboard.
+    */
     for (var photo_id in divs)
     {
         var photo_div = divs[photo_id];
@@ -184,6 +197,10 @@ function refresh_divs()
 
 function request_more_divs()
 {
+    /*
+    Using the ids in `needed`, download more photo card divs and place them
+    into `divs`, so that `refresh_divs` can then add them to the page.
+    */
     if (needed.size == 0)
     {
         return;
@@ -206,6 +223,7 @@ function request_more_divs()
             holder.appendChild(photo_div);
         }
         photo_clipboard.apply_check_all();
+        console.log("Needed but not received: " + Array.from(needed));
     }
     common.post(url, data, callback);
 }
diff --git a/frontends/etiquette_flask/templates/clipboard_tray.html b/frontends/etiquette_flask/templates/clipboard_tray.html
index eefccc5..cf56302 100644
--- a/frontends/etiquette_flask/templates/clipboard_tray.html
+++ b/frontends/etiquette_flask/templates/clipboard_tray.html
@@ -11,7 +11,10 @@
                 <a target="_blank" href="/clipboard">Full clipboard</a>
                 <button id="clear_clipboard_button" class="red_button" onclick="photo_clipboard.clear_clipboard()">Clear</button>
             </span>
-            <!-- More elements can be added here by the page. -->
+            <!--
+            If the page contains a div with the class `my_clipboard_tray_toolbox`,
+            the children of that div will be appended here.
+            -->
         </div>
         <div id="clipboard_tray_lines">
         </div>