Polishing comments.

1 files changed, 83 insertions, 73 deletions

diff --git a/js/backoffice.js b/js/backoffice.js
index fc223d6..187ebf5 100644
--- a/js/backoffice.js
+++ b/js/backoffice.js
@@ -27,17 +27,41 @@
 */
 "use strict";
 
+/**
+ * The precision of the amount's fraction, when
+ * it comes objectified.
+ */
 var FRACTION = 100000000;
+
+/**
+ * Default 'start' URL argument used when querying for /history.
+ */
 var START = 0;
+
+/**
+ * Fixed 'delta' URL argument used when querying for /history.
+ */
 var DELTA = 5
+
+/**
+ * Row id of the _oldest_ /history record that's shown on the
+ * screen; will be used as the next 'delta' argument if scrolling
+ * down occurs.
+ */
 var LAST = 0;
+
+/**
+ * Flag controlling whether the scrolling of the page is enabled
+ * or not; for example, after /track/transfer results are shown
+ * on page, the semantics of "scrolling down towards older records"
+ * disappears because former results aren't arranged regarding of
+ * time.
+ */
 var SCROLL = true;
 
 /**
- * This function *could* "type check" 'amount',
- * but once 'amount' got here it is already "too late",
- * because this means that the merchant *backend* gave
- * it wrong.
+ * Convert Taler-compliant amount to human-friendly string.
+ * The amount may be both a string or object type.
  */
 function amount_to_string(amount){
   if (typeof amount === 'string' || amount instanceof String)
@@ -54,6 +78,12 @@ function amount_to_string(amount){
   return `${number.toFixed(2)} ${amount.currency}`;
 }
 
+
+/**
+ * Close the center-box that shows results from /track/transaction
+ * Note that this function first *empties* the results, and then
+ * closes the box.
+ */
 function close_popup(){
 
   var ctx = document.getElementsByClassName("track-content")[0];
@@ -67,18 +97,6 @@ function close_popup(){
   toggle_overlay(true);
 }
 
-function amount_sum(a1, a2){
-  if(a1.currency != a2.currency)
-    throw "Currency mismatch, terminating.";
-  var ret = {currency: a2.currency,
-             value: 0,
-             fraction: 0};
-  ret.value = a1.value + a2.value;
-  var fraction = a1.fraction + a2.fraction;
-  ret.value += Math.floor(fraction / FRACTION);
-  ret.fraction = fraction % FRACTION;
-  return ret;
-}
 
 /**
  * Parse Taler /Date(x)/ into human-friendly format.
@@ -105,7 +123,8 @@ function parse_date(date){
 
 /**
  * Make screen-centerd box (which show a order's tracks)
- * appear/disappear.
+ * appear/disappear.  Note, this function does NOT check if
+ * the box has content or not.
  */
 function toggle_overlay(force_close){
   var overlay = document.getElementsByClassName("overlay")[0];
@@ -122,8 +141,8 @@ function toggle_overlay(force_close){
 }
 
 /**
- * Draws a line at the bottom of a orders list to indicate
- * they have all being paid out by the same WTID.
+ * Draws a line at the bottom of a orders list to
+ * indicate they have all being paid out by the same WTID.
  */
 function make_marker(wtid){
   var tr = document.createElement("tr");
@@ -141,17 +160,15 @@ function make_marker(wtid){
 /**
  * Use the /track/transfer API from the frontend.  Once data
  * arrives, it calls a UI function which lists all the entries
- * in the page.
- *
- * 'cb' is a UI transforming function.  Typically, it is set to
- * 'fill_table()'.
+ * in the page.  Results will be shown in the same style of
+ * /history's.
  */
 var track_transfer = function(exchange, wtid, cb){
 
-  /* Remove any previous errors, if there are any.  */
+  /* Remove potential information bar.  */
   var info_bar = document.getElementById("information-bar");
   info_bar.style.visibility = "hidden"; 
-  /* Will be untoggled by the 'cb' */
+
   toggle_loader();
   var qs = `/track/transfer?` +
            `exchange=${exchange}&` +
@@ -185,8 +202,10 @@ var track_transfer = function(exchange, wtid, cb){
 }
 
 
-/* Fill the information bar on the top of the page with
- * error messages.  */
+/**
+ * Fill the information bar on the top of the page with
+ * error messages.  The same orange bar is used for warnings.
+ */
 var show_warning;
 var show_error = show_warning = function(response_text){
 
@@ -209,27 +228,22 @@ var show_error = show_warning = function(response_text){
     console.log("Must keep raw response");
   }
   
-  /* msg is ready here.  */
-
   /* Get hold of the info bar.  */
   var info_bar = document.getElementById("information-bar");
   info_bar.innerHTML = `<p>${msg}</p>`; 
   info_bar.style.visibility = "visible"; 
-
-  /* Info bar will disappear at next page load/reload.  */
 }
 
 /**
- * Call /track/order API offered by the frontend.  Once data
- * arrives it calls a UI routine which fills the "entries table"
- * in the page.
+ * Call /track/order API offered by the frontend.  It will make
+ * results shown in a centered box that overlays the page.
  */
 var track_order = function(order_id, cb){
   
-  /* Remove any previous errors, if there are any.  */
+  /* Remove potential information bar.  */
   var info_bar = document.getElementById("information-bar");
   info_bar.style.visibility = "hidden"; 
-  /* Will be untoggled by the 'cb' */
+
   toggle_loader();
   var req = new XMLHttpRequest();
   var url = `/track/order?` +
@@ -250,6 +264,8 @@ var track_order = function(order_id, cb){
 
 /**
  * Fill the screen-centered box with data from /track/order.
+ * This box will overlay the ordinary page, and disappear when
+ * the user clicks the close button or Esc key.
  */
 function fill_box(tracks, http_code)
 {
@@ -268,6 +284,7 @@ function fill_box(tracks, http_code)
   }
 
   if(!tracks)
+    show_error("/track/transfer returned EMPTY!  Very bad.");
     console.log("Got invalid JSON");
     if(0 == tracks.length || !tracks.length){
       console.log(`Got no tracks and status == ${http_code}.  ` +
@@ -278,12 +295,6 @@ function fill_box(tracks, http_code)
 
   for(var i=0; i<tracks.length; i++){
     var entry = tracks[i];
-    /**
-     * 'track_content' contains the tracks (WTID/Amount/Date)
-     * about *one* order.  It is contained in the 'overlay',
-     * which renders it in a "box" in the middle of the
-     * screen.  This "box" is then toggleable as visible/hidden.
-     */
     var overlay = document.getElementsByClassName("overlay")[0];
     var track_content = document.getElementsByClassName
       ("track-content")[0];
@@ -330,15 +341,16 @@ function xpath_get(xpath, ctx){
 }
 
 
+/**
+ * Fill the page with orders rows.
+ */
 function fill_table(data, execution_time, wtid_marker){
   var table = document.getElementById("history");
   var tbody = xpath_get("tbody", table).snapshotItem(0);
 
-  /* Make table's headers visible */
+  /* Make table visible, if it's hidden.  */
   xpath_get("tr[@class='headers']", tbody)
     .snapshotItem(0).style.visibility = "visible";
-  /* Will only be effective on page first load; afterwards
-   * it is just idempotent.  */
   table.style.visibility = "visible";
 
   for (var i=0; i<data.length; i++){
@@ -385,8 +397,7 @@ function fill_table(data, execution_time, wtid_marker){
 }
 
 /**
- * Make the spinning wheel appear if it is not shown,
- * and viceversa.
+ * Make the spinning wheel appear/disappear.
  */
 function toggle_loader(){
   var loader = document.getElementsByClassName("loader")[0]; 
@@ -405,7 +416,7 @@ function toggle_loader(){
 /**
  * Issue a /track/order (/track/transfer) depending on
  * whether the user selected "order" ("transfer") on the
- * given form.
+ * dedicated form.
  */
 function track_cherry_pick(form){
   var types = xpath_get("input[@type='radio']", form);
@@ -428,17 +439,7 @@ function track_cherry_pick(form){
 }
 
 /**
- * The "cherry pick" form allows the user to track a particular
- * order or wire transfer by entering its "id" in the input field.
- *
- * The UI is such that a radio button can switch the form "type"
- * to query for a order or for a wire transfer;  the following two
- * functions help to switch the form appearance according to this
- * order/wire-transfer switch.
- */
-
-/**
- * Make the "cherry pick" form be suitable to query /track/order.
+ * Make the /track/order form visible.
  */
 function cherry_pick_form_order(form){
   var input_order = xpath_get("input[@class='order']", form)
@@ -450,7 +451,7 @@ function cherry_pick_form_order(form){
 }
 
 /**
- * Make the "cherry pick" form be suitable to query /track/transfer.
+ * Make the /track/transaction form visible.
  */
 function cherry_pick_form_transfer(form){
   var input_order = xpath_get("input[@class='order']", form)
@@ -462,7 +463,7 @@ function cherry_pick_form_transfer(form){
 }
 
 /**
- * Retrieve current istance being tracked.
+ * Retrieve the selected instance.
  */
 function get_instance(){
   var select = document.getElementById("instance");
@@ -470,8 +471,8 @@ function get_instance(){
 }
 
 /**
- * Remove tracks from the main page table, but do NOT remove
- * the table headers
+ * Remove tracks from the main page table, but
+ * do NOT remove the table headers; it hides them though.
  */
 function clear_results(){
   var table = document.getElementById("history");
@@ -485,9 +486,11 @@ function clear_results(){
     .snapshotItem(0).style.visibility = "hidden";
 
 }
+
+
 /**
- * Nullify curreny instance and triggers history for newly
- * selected one.
+ * Make the instance selected effective.  In particular, it
+ * triggers history retrieval for it.
  */
 function change_instance(){
   /* Restore values.  Changing instance should have
@@ -504,13 +507,7 @@ function change_instance(){
 }
 
 /**
- * If 'scroll' is true, the logic tries to retrieve the
- * "next page" of all the proposals known to the merchant.
- * Otherwise, it gets the merchant's history from the beginning
- * of their business.
- *
- * 'cb' is a UI transforming function.  Typically, it is set
- * to 'fill_table()'.
+ * Query the /history API.
  */
 function get_history(scroll, cb){
   SCROLL = true;
@@ -551,11 +548,18 @@ function get_history(scroll, cb){
   req.send();
 }
 
+/**
+ * Trigger /history as soon as the page loads.
+ */
 document.addEventListener
   ("DOMContentLoaded",
    function(){
      get_history(false, fill_table);});
 
+/**
+ * Implement scrolling down of history.  When the user
+ * scrolls down, older results from /history will be requested.
+ */
 document.addEventListener
   ("scroll", function(){
   /* If page bottom is hit */
@@ -564,7 +568,10 @@ document.addEventListener
     get_history(true, fill_table);
   });
 
-/* Close dialog on ESC press */
+/**
+ * Close the centered box that (typically) shows /track/transfer
+ * results.
+ */
 document.onkeydown = function(e) {
   if(!e)
     e = event;
@@ -573,6 +580,9 @@ document.onkeydown = function(e) {
   }
 }
 
+/**
+ * export functions to be tested by AVA.
+ */
 if (typeof(module) != "undefined"){
   module.exports.track_transfer = track_transfer;
   module.exports.track_order = track_order;