[GCI] Standardised UI code comments (#1345)

* standardise comments

* fix some stuff

* A googol issues fixed

* Update examples/demo.js

* .

* .

Co-authored-by: Jeffrey Warren <jeff@unterbahn.com>

examples/demo.js

@@ -6,7 +6,7 @@ var defaultHtmlSequencerUi = require('./lib/defaultHtmlSequencerUi.js'),
   insertPreview = require('./lib/insertPreview.js');
 
 window.onload = function () {
-  sequencer = ImageSequencer();
+  sequencer = ImageSequencer(); // Set the global sequencer variable
   
   options = {
     sortField: 'text',
@@ -52,7 +52,10 @@ window.onload = function () {
 
   $(window).on('scroll', scrollFunction);
 
-  function scrollFunction() {
+  /**
+   * @description Method to toggle the scroll-up arrow.
+   */
+  function scrollFunction(A, B) {
     var shouldDisplay = $('body').scrollTop() > 20 || $(':root').scrollTop() > 20;
 
     $('#move-up').css({
@@ -60,7 +63,9 @@ window.onload = function () {
     });
   }
 
-
+  /**
+   * @description Method to scroll to the top of the page.
+   */
   function topFunction() {
     $('body').animate({scrollTop: 0});
     $(':root').animate({scrollTop: 0});
@@ -75,7 +80,7 @@ window.onload = function () {
   // UI for the overall demo:
   var ui = defaultHtmlSequencerUi(sequencer);
 
-  // find any `src` parameters in URL hash and attempt to source image from them and run the sequencer
+  // Load image data from URL `src` parameter.
   if (urlHash.getUrlHashParameter('src')) {
     sequencer.loadImage(urlHash.getUrlHashParameter('src'), ui.onLoad);
   } else {
@@ -92,18 +97,23 @@ window.onload = function () {
   $('#addStep #add-step-btn').on('click', ui.addStepUi);
   $('#resetButton').on('click', resetSequence);
 
-  //Module button radio selection
+  // Module Selector quick buttons click handler.
   $('.radio-group .radio').on('click', function () {
     $(this).parent().find('.radio').removeClass('selected');
     $(this).addClass('selected');
     newStep = $(this).attr('data-value');
-    //$("#addStep option[value=" + newStep + "]").attr('selected', 'selected');
+
     $('#addStep select').val(newStep);
     ui.selectNewStepUi(newStep);
     ui.addStepUi(newStep);
     $(this).removeClass('selected');
   });
 
+  /**
+   * @method displayMessageOnSaveSequence
+   * @description When a sequence is saved to a browser, notification is displayed.
+   * @returns {Null}
+   */
   function displayMessageOnSaveSequence() {
     $('.savesequencemsg').fadeIn();
     setTimeout(function () {
@@ -123,7 +133,7 @@ window.onload = function () {
     }
   }
   $('#saveButton').on('click', function () {
-    // different handlers triggered for different dropdown options
+    // Different handlers triggered for different dropdown options.
 
     let dropDownValue = $('#selectSaveOption option:selected').val();
 
@@ -145,9 +155,8 @@ window.onload = function () {
 
   let isWorkingOnGifGeneration = false;
 
-  $('.js-view-as-gif').on('click', function (event) {
+  $('.js-view-as-gif').on('click', function (event) { // GIF generation and display
-    /* Prevent user from triggering generation multiple times*/
+    if (isWorkingOnGifGeneration) return; // Prevent multiple button clicks
-    if (isWorkingOnGifGeneration) return;
 
     isWorkingOnGifGeneration = true;
 
@@ -156,12 +165,12 @@ window.onload = function () {
     button.innerHTML = '<i class="fa fa-circle-o-notch fa-spin"></i>';
 
     try {
-      /* Get gif resources of previous steps  */
+      // Get GIF resources from previous steps
       let options = getGifResources();
 
-      gifshot.createGIF(options, function (obj) { // gif generation
+      gifshot.createGIF(options, function (obj) { // GIF generation
         if (!obj.error) {
-          // Final gif encoded with base64 format
+          // Final GIF encoded with base64 format
           var image = obj.image;
           var animatedImage = document.createElement('img');
 
@@ -171,9 +180,7 @@ window.onload = function () {
           let modal = $('#js-download-gif-modal');
 
           $('#js-download-as-gif-button').one('click', function () {
-            // Trigger download
+            downloadGif(image); // Trigger GIF download
-            downloadGif(image);
-            // Close modal
             modal.modal('hide');
           });
 
@@ -185,7 +192,6 @@ window.onload = function () {
           // Insert image
           gifContainer.appendChild(animatedImage);
 
-
           // Open modal
           modal.modal();
 
@@ -204,16 +210,16 @@ window.onload = function () {
   });
 
   function getGifResources() {
-    /* Returns an object with specific gif options */
+    // Returns an object with specific gif options
     let imgs = document.getElementsByClassName('step-thumbnail');
     var imgSrcs = [];
 
-    // Pushes image sources of all the modules in dom
+    // Pushes image sources of all the modules in the DOM
     for (var i = 0; i < imgs.length; i++) {
       imgSrcs.push(imgs[i].src);
     }
 
-    var options = { // gif frame options
+    var options = { // GIF frame options
       'gifWidth': imgs[0].width,
       'gifHeight': imgs[0].height,
       'images': imgSrcs,
@@ -271,7 +277,7 @@ window.onload = function () {
 
 
   function downloadGif(image) {
-    download(image, 'index.gif', 'image/gif');// downloadjs library function
+    download(image, 'index.gif', 'image/gif'); // Downloadjs library function
   }
 
   function SaveToPubliclab() {
@@ -286,7 +292,7 @@ window.onload = function () {
     postToPL($('img')[sequencer.steps.length - 1].src);
   }
 
-  // image selection and drag/drop handling from examples/lib/imageSelection.js
+  // Image selection and drag/drop handling from examples/lib/imageSelection.js
   sequencer.setInputStep({
     dropZoneSelector: '#dropzone',
     fileInputSelector: '#fileInput',
@@ -318,7 +324,7 @@ window.onload = function () {
 
   setupCache();
 
-  if (urlHash.getUrlHashParameter('src')) {
+  if (urlHash.getUrlHashParameter('src')) {  // Gets the sequence from the URL
     insertPreview.updatePreviews(urlHash.getUrlHashParameter('src'), document.querySelector('#addStep'));
   } else {
     insertPreview.updatePreviews('images/tulips.png', document.querySelector('#addStep'));

examples/lib/defaultHtmlStepUi.js

@@ -23,7 +23,7 @@ function DefaultHtmlStepUi(_sequencer, options) {
     if (step.options && step.options.description)
       step.description = step.options.description;
 
-    step.ui =
+    step.ui = // Basic UI markup for the step
       '\
       <div class="container-fluid step-container">\
           <div class="panel panel-default">\
@@ -72,18 +72,20 @@ function DefaultHtmlStepUi(_sequencer, options) {
     var util = intermediateHtmlStepUi(_sequencer, step);
 
     var parser = new DOMParser();
-    step.ui = parser.parseFromString(step.ui, 'text/html');
+    step.ui = parser.parseFromString(step.ui, 'text/html'); // Convert the markup string to a DOM node.
     step.ui = step.ui.querySelector('div.container-fluid');
-    step.$step = scopeQuery.scopeSelector(step.ui);
+
+    step.$step = scopeQuery.scopeSelector(step.ui); // Shorthand methods for scoped DOM queries. Read the docs [CONTRIBUTING.md](https://github.com/publiclab/image-sequencer/blob/main/CONTRIBUTING.md) for more info.
     step.$stepAll = scopeQuery.scopeSelectorAll(step.ui);
     let {$step, $stepAll} = step;
-    step.linkElements = step.ui.querySelectorAll('a');
+    
-    step.imgElement = $step('a img.img-thumbnail')[0];
+    step.linkElements = step.ui.querySelectorAll('a'); // All the anchor tags in the step UI
+    step.imgElement = $step('a img.img-thumbnail')[0]; // The output image
 
     if (_sequencer.modulesInfo().hasOwnProperty(step.name)) {
       var inputs = _sequencer.modulesInfo(step.name).inputs;
       var outputs = _sequencer.modulesInfo(step.name).outputs;
-      var merged = Object.assign(inputs, outputs); // combine outputs w inputs
+      var merged = Object.assign(inputs, outputs); // Combine outputs with inputs
 
       for (var paramName in merged) {
         var isInput = inputs.hasOwnProperty(paramName);
@@ -103,7 +105,7 @@ function DefaultHtmlStepUi(_sequencer, options) {
         else {
           let paramVal = step.options[paramName] || inputDesc.default;
 
-          if (inputDesc.id == 'color-picker') { // separate input field for color-picker
+          if (inputDesc.id == 'color-picker') { // Separate input field for color-picker
             html +=
               '<div id="color-picker" class="input-group colorpicker-component">' +
               '<input class="form-control target" type="' +
@@ -114,7 +116,7 @@ function DefaultHtmlStepUi(_sequencer, options) {
               paramVal + '">' + '<span class="input-group-addon"><i></i></span>' +
               '</div>';
           }
-          else { // use this if the the field isn't color-picker
+          else { // Non color-picker input types
             html =
               '<input class="form-control target" type="' +
               inputDesc.type +
@@ -156,10 +158,10 @@ function DefaultHtmlStepUi(_sequencer, options) {
                          </div>';
         $step('div.details').append(div);
       }
-      $step('div.panel-footer').append(
+      $step('div.panel-footer').append( // Save button
         '<div class="cal collapse in"><button type="submit" class="btn btn-sm btn-default btn-save" disabled = "true" >Apply</button> <small style="padding-top:2px;">Press apply to see changes</small></div>'
       );
-      $step('div.panel-footer').prepend(
+      $step('div.panel-footer').prepend( // Markup for tools: download and insert step buttons
         '<button class="pull-right btn btn-default btn-sm insert-step" >\
         <span class="insert-text"><i class="fa fa-plus"></i> Insert Step</span><span class="no-insert-text" style="display:none">Close</span></button>\
         <button class="pull-right btn btn-default btn-sm download-btn" style="margin-right:2px" >\
@@ -174,9 +176,10 @@ function DefaultHtmlStepUi(_sequencer, options) {
           parser.parseFromString(tools, 'text/html').querySelector('div')
         );
 
-      $stepAll('.remove').on('click', function() {notify('Step Removed', 'remove-notification');});
+      $stepAll('.remove').on('click', function() {notify('Step Removed', 'remove-notification');}); // Notification on removal of a step
-      $step('.insert-step').on('click', function() { util.insertStep(step.ID); });
+      $step('.insert-step').on('click', function() { util.insertStep(step.ID); }); // Insert a step in between the sequence
       // Insert the step's UI in the right place
+
       if (stepOptions.index == _sequencer.steps.length) {
         stepsEl.appendChild(step.ui);
         $('#steps .step-container:nth-last-child(1) .insert-step').prop('disabled', true);
@@ -193,8 +196,7 @@ function DefaultHtmlStepUi(_sequencer, options) {
       else $('#load-image .insert-step').prop('disabled', true);
     }
     else {
-      $('#load-image').append(step.ui);
+      $('#load-image').append(step.ui); // Default UI without extra tools for the first step(load image)
-
 
       $step('div.panel-footer').prepend( `
           <button class="right btn btn-default btn-sm insert-step" disabled="true">
@@ -205,12 +207,12 @@ function DefaultHtmlStepUi(_sequencer, options) {
 
       $step('.insert-step').on('click', function() { util.insertStep(step.ID); });
     }
-    $step('.toggle').on('click', () => {
+    $step('.toggle').on('click', () => { // Step container dropdown
       $step('.toggleIcon').toggleClass('rotated');
       $stepAll('.cal').collapse('toggle');
     });
     
-    $(step.imgElement).on('mousemove', _.debounce(() => imageHover(step), 150));
+    $(step.imgElement).on('mousemove', _.debounce(() => imageHover(step), 150)); // Shows the pixel coordinates on hover
     $(step.imgElement).on('click', (e) => {e.preventDefault(); });
     $stepAll('#color-picker').colorpicker();
 
@@ -227,15 +229,23 @@ function DefaultHtmlStepUi(_sequencer, options) {
           });
         _sequencer.run({ index: step.index - 1 });
 
-        // modify the url hash
+        // Modify the URL hash
         urlHash.setUrlHashParameter('steps', _sequencer.toString());
-        // disable the save button
+        // Disable the save button
         $step('.btn-save').prop('disabled', true);
         optionsChanged = false;
         changedInputs = 0;
       }
     }
 
+    /**
+     * @method handleInputValueChange
+     * @description Enables the save button on input change
+     * @param {*} currentValue The current value of the input
+     * @param {*} initValue The initial/old value of the input
+     * @param {Boolean} hasChangedBefore Whether the input was changed before
+     * @returns {Boolean} True if the value has changed
+     */
     function handleInputValueChange(currentValue, initValue, hasChangedBefore) {
       var inputChanged = !(isNaN(initValue) || isNaN(currentValue) ? currentValue === initValue : currentValue - initValue === 0);
       changedInputs += hasChangedBefore ? inputChanged ? 0 : -1 : inputChanged ? 1 : 0;
@@ -293,7 +303,7 @@ function DefaultHtmlStepUi(_sequencer, options) {
         step.linkElements[index].href = step.imgElement.src;
     }
 
-    // TODO: use a generalized version of this
+    // TODO: use a generalized version of this.
     function fileExtension(output) {
       return output.split('/')[1].split(';')[0];
     }
@@ -314,7 +324,7 @@ function DefaultHtmlStepUi(_sequencer, options) {
       }
     });
 
-    // fill inputs with stored step options
+    // Fill inputs with stored step options
     if (_sequencer.modulesInfo().hasOwnProperty(step.name)) {
       var inputs = _sequencer.modulesInfo(step.name).inputs;
       var outputs = _sequencer.modulesInfo(step.name).outputs;
@@ -353,6 +363,12 @@ function DefaultHtmlStepUi(_sequencer, options) {
     else $step('.wasm-tooltip').fadeOut();
   }
 
+  /**
+   * @method imageHover
+   * @description Handler to display image coordinates on hover.
+   * @param {Object} step Current step variable
+   * @returns {Null}
+   */
   function imageHover(step){
 
     var img = $(step.imgElement);
@@ -388,6 +404,13 @@ function DefaultHtmlStepUi(_sequencer, options) {
     return step.imgElement;
   }
 
+  /**
+   * @method notify
+   * @description General purpose DOM toast notification
+   * @param {String} msg Message to be displayed
+   * @param {String} id A unique identifier for the notification
+   * @returns {Null}
+   */
   function notify(msg, id){
     if ($('#' + id).length == 0) {
       var notification = document.createElement('span');

examples/lib/intermediateHtmlStepUi.js

@@ -1,8 +1,17 @@
 var urlHash = require('./urlHash.js'),
   insertPreview = require('./insertPreview.js');
 
+/**
+ * @method IntermediateHtmlStepUi
+ * @description Inserts a module selector in between the current sequence
+ * @param {Object} _sequencer Sequencer instance
+ * @param {Object} step Current step variable
+ * @param {Object} options Optional options Object
+ * @returns {Object} Object containing the insertStep function
+ */
 function IntermediateHtmlStepUi(_sequencer, step, options) {
   function stepUI() {
+    // Basic markup for the selector
     return '<div class="row insertDiv collapse">\
           <section class="panel panel-primary .insert-step">\
             <button class="btn btn-default close-insert-box"><i class="fa fa-times" aria-hidden="true"></i> Close</button>\
@@ -64,6 +73,13 @@ function IntermediateHtmlStepUi(_sequencer, step, options) {
         </div>';
   }
 
+  /**
+   * @method toggleDiv
+   * @description Toggles the module selector dropdown.
+   * @param {Object} $step $step util function
+   * @param {Fucntion} callback Optional callback function
+   * @returns {Null}
+   */
   var toggleDiv = function($step, callback = function(){}){
     $step('.insertDiv').collapse('toggle');
     if ($step('.insert-text').css('display') != 'none'){
@@ -74,6 +90,11 @@ function IntermediateHtmlStepUi(_sequencer, step, options) {
     }
   };
 
+  /**
+   * @method insertStep
+   * @description Handler to insert selected module in the sequence
+   * @returns {Null}
+   */
   insertStep = function (id) {
     const $step = step.$step,
       $stepAll = step.$stepAll;
@@ -119,9 +140,9 @@ function IntermediateHtmlStepUi(_sequencer, step, options) {
     });
 
     $('.insertDiv .radio-group .radio').on('click', function () {
-      var newStepName = $(this).attr('data-value');
+      var newStepName = $(this).attr('data-value'); // Get the name of the module to be inserted
       id = $($step('.insertDiv').parents()[3]).prevAll().length;
-      insert(id, $step, newStepName);
+      insert(id, $step, newStepName); // Insert the selected module
     });
 
     $step('.insertDiv .add-step-btn').on('click', function () {
@@ -130,6 +151,13 @@ function IntermediateHtmlStepUi(_sequencer, step, options) {
       insert(id, $step, newStepName); });
   };
 
+  /**
+   * @method insert
+   * @description Inserts the specified step at the specified index in the sequence
+   * @param {Number} id Index of the step
+   * @param {Function} $step $step util function
+   * @param {String} newStepName Name of the new step
+   */
   function insert(id, $step, newStepName) {
     toggleDiv($step);
     $step('.insertDiv').removeClass('insertDiv');