[GCI] Standardised UI code comments

examples/demo.js

@@ -6,16 +6,16 @@ var defaultHtmlSequencerUi = require('./lib/defaultHtmlSequencerUi.js'),
   insertPreview = require('./lib/insertPreview.js');
 
 window.onload = function () {
-  sequencer = ImageSequencer();
+  sequencer = ImageSequencer(); // Set the global sequencer variable.
 
   function refreshOptions() {
-    // Load information of all modules (Name, Inputs, Outputs)
+    // Load information (Name, Inputs, Outputs) of all modules.
     var modulesInfo = sequencer.modulesInfo();
 
     var addStepSelect = $('#addStep select');
     addStepSelect.html('');
 
-    // Add modules to the addStep dropdown
+    // Add modules to the addStep dropdown.
     for (var m in modulesInfo) {
       if (modulesInfo[m] && modulesInfo[m].name)
         addStepSelect.append(
@@ -32,6 +32,9 @@ window.onload = function () {
 
   $(window).on('scroll', scrollFunction);
 
+  /**
+   * @description Method to toggle the scroll-up arro
+   */
   function scrollFunction() {
     var shouldDisplay = $('body').scrollTop() > 20 || $(':root').scrollTop() > 20;
 
@@ -41,6 +44,9 @@ window.onload = function () {
   }
 
 
+  /**
+   * @description Method to scroll to the top of the page.
+   */
   function topFunction() {
     $('body').animate({scrollTop: 0});
     $(':root').animate({scrollTop: 0});
@@ -55,7 +61,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 {
@@ -72,18 +78,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 () {
@@ -103,7 +114,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();
 
@@ -120,9 +131,8 @@ window.onload = function () {
 
   let isWorkingOnGifGeneration = false;
 
-  $('.js-view-as-gif').on('click', function (event) {
-    /* Prevent user from triggering generation multiple times*/
-    if (isWorkingOnGifGeneration) return;
+  $('.js-view-as-gif').on('click', function (event) { // GIF generation and display.
+    if (isWorkingOnGifGeneration) return; // Prevent multiple button clicks.
 
     isWorkingOnGifGeneration = true;
 
@@ -131,12 +141,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');
 
@@ -146,22 +156,19 @@ window.onload = function () {
           let modal = $('#js-download-gif-modal');
 
           $('#js-download-as-gif-button').one('click', function () {
-            // Trigger download
-            downloadGif(image);
-            // Close modal
+            downloadGif(image); // Trigger GIF download.
             modal.modal('hide');
           });
 
           var gifContainer = document.getElementById('js-download-modal-gif-container');
 
-          // Clear previous results
+          // Clear previous results.
           gifContainer.innerHTML = '';
 
-          // Insert image
+          // Insert image.
           gifContainer.appendChild(animatedImage);
 
-
-          // Open modal
+          // Open modal.
           modal.modal();
 
           button.disabled = false;
@@ -179,16 +186,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,
@@ -208,10 +215,10 @@ window.onload = function () {
   }
 
   function downloadGif(image) {
-    download(image, 'index.gif', 'image/gif');// downloadjs library function
+    download(image, 'index.gif', 'image/gif'); // Downloadjs library function.
   }
 
-  // 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',
@@ -244,9 +251,9 @@ window.onload = function () {
 
   setupCache();
 
-  if (urlHash.getUrlHashParameter('src')) {
+  if (urlHash.getUrlHashParameter('src')) { // Gets the sequence from the URL.
     insertPreview.updatePreviews(urlHash.getUrlHashParameter('src'), '#addStep');
   } else {
     insertPreview.updatePreviews('images/tulips.png', '#addStep');
   }
-};
+};

examples/lib/defaultHtmlStepUi.js

@@ -16,7 +16,6 @@ const intermediateHtmlStepUi = require('./intermediateHtmlStepUi.js'),
 
 function DefaultHtmlStepUi(_sequencer, options) {
   let $step, $stepAll;
-
   options = options || {};
   var stepsEl = options.stepsEl || document.querySelector('#steps');
   var selectStepSel = options.selectStepSel = options.selectStepSel || '#selectStep';
@@ -26,7 +25,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">\
@@ -68,21 +67,21 @@ 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 = scopeQuery.scopeSelector(step.ui);
+    $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.
     $stepAll = scopeQuery.scopeSelectorAll(step.ui);
     step.ui.$step = $step;
     step.ui.$stepAll = $stepAll;
 
-    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);
@@ -102,7 +101,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="' +
@@ -113,7 +112,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 +
@@ -155,10 +154,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" >\
@@ -173,9 +172,9 @@ function DefaultHtmlStepUi(_sequencer, options) {
           parser.parseFromString(tools, 'text/html').querySelector('div')
         );
 
-      $stepAll('.remove').on('click', function() {notify('Step Removed', 'remove-notification');});
-      $stepAll('.insert-step').on('click', function() { util.insertStep(step.ID); });
-      // Insert the step's UI in the right place
+      $stepAll('.remove').on('click', function() {notify('Step Removed', 'remove-notification');}); // Notification on removal of a step.
+      $stepAll('.insert-step').on('click', function() { util.insertStep(step.ID); }); // Insert a step in between the sequence.
+
       if (stepOptions.index == _sequencer.steps.length) {
         stepsEl.appendChild(step.ui);
         $('#steps .step-container:nth-last-child(1) .insert-step').prop('disabled', true);
@@ -187,14 +186,14 @@ function DefaultHtmlStepUi(_sequencer, options) {
       }
     }
     else {
-      $('#load-image').append(step.ui);
+      $('#load-image').append(step.ui); // Default UI without extra tools for the first step(load image).
     }
-    $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();
 
@@ -211,15 +210,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;
@@ -276,7 +283,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];
     }
@@ -297,7 +304,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;
@@ -328,6 +335,12 @@ function DefaultHtmlStepUi(_sequencer, options) {
     });
   }
 
+  /**
+   * @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);
@@ -357,6 +370,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');
@@ -388,4 +408,4 @@ if(typeof window === 'undefined'){
   };
 }
 
-module.exports = DefaultHtmlStepUi;
+module.exports = DefaultHtmlStepUi;