[GCI] Standardised Core code comments (#1343)

* standardise comments

* fix

* fixes

* add docs links

* remove extra .

* ., this and other changes

Author: harshkhandeparkar

src/ImageSequencer.js

@@ -2,6 +2,11 @@ if (typeof window !== 'undefined') { isBrowser = true; }
 else { var isBrowser = false; }
 require('./util/getStep.js');
 
+/**
+ * @method ImageSequencer
+ * @param {Object|Float32Array} options Optional options
+ * @returns {Object}
+ */
 ImageSequencer = function ImageSequencer(options) {
 
   var str = require('./Strings.js')(this.steps, modulesInfo, addSteps, copy);
@@ -14,13 +19,25 @@ ImageSequencer = function ImageSequencer(options) {
     return Object.prototype.toString.call(object).split(' ')[1].slice(0, -1);
   }
 
+  /**
+   * @method log
+   * @description Logs colored messages to the console using ASCII color codes
+   * @param {String} color ASCII color code
+   * @param {String} msg Message to be logged to the console
+   */
   function log(color, msg) {
     if (options.ui != 'none') {
       if (arguments.length == 1) console.log(arguments[0]);
       else if (arguments.length == 2) console.log(color, msg);
     }
   }
 
+  /**
+   * @method copy
+   * @description Returns a clone of the input object.
+   * @param {Object|Float32Array} a The Object/Array to be cloned
+   * @returns {Object|Float32Array}
+   */
   function copy(a) {
     if (!typeof (a) == 'object') return a;
     if (objTypeOf(a) == 'Array') return a.slice();
@@ -53,22 +70,27 @@ ImageSequencer = function ImageSequencer(options) {
     for (o in sequencer) {
       modules[o] = sequencer[o];
     }
-    sequences = JSON.parse(window.localStorage.getItem('sequences'));
+    sequences = JSON.parse(window.localStorage.getItem('sequences')); // Get saved sequences from localStorage
     if (!sequences) {
       sequences = {};
-      window.localStorage.setItem('sequences', JSON.stringify(sequences));
+      window.localStorage.setItem('sequences', JSON.stringify(sequences)); // Set the localStorage entry as an empty Object by default
     }
   }
 
   // if in browser, prompt for an image
   // if (options.imageSelect || options.inBrowser) addStep('image-select');
   // else if (options.imageUrl) loadImage(imageUrl);
 
+  /**
+   * @method addSteps
+   * @description Adds one of more steps to the sequence.
+   * @return {Object}
+   */
   function addSteps() {
     var this_ = (this.name == 'ImageSequencer') ? this : this.sequencer;
     var args = [];
     var json_q = {};
-    for (var arg in arguments) { args.push(copy(arguments[arg])); }
+    for (var arg in arguments) { args.push(copy(arguments[arg])); } // Get all the module names from the arguments
     json_q = formatInput.call(this_, args, '+');
 
     inputlog.push({ method: 'addSteps', json_q: copy(json_q) });
@@ -77,17 +99,28 @@ ImageSequencer = function ImageSequencer(options) {
     return this;
   }
 
+  /**
+   * @method removeStep
+   * @description Removes the step at the specified index from the sequence.
+   * @param {Object} ref ImageSequencer instance
+   * @param {Number} index Index of the step to be removed
+   * @returns {Null}
+   */
   function removeStep(ref, index) {
-    //remove the step from images[image].steps and redraw remaining images
+    // Remove the step from images[image].steps and redraw remaining images
     if (index > 0) {
-      //var this_ = (this.name == "ImageSequencer") ? this : this.sequencer;
+      // var this_ = (this.name == "ImageSequencer") ? this : this.sequencer;
       thisStep = ref.steps[index];
       thisStep.UI.onRemove(thisStep.options.step);
       ref.steps.splice(index, 1);
     }
-    //tell the UI a step has been removed
   }
 
+  /**
+   * @method removeSteps
+   * @description Removes one or more steps from the sequence
+   * @returns {Object}
+   */
   function removeSteps() {
     var   indices;
     var this_ = (this.name == 'ImageSequencer') ? this : this.sequencer;
@@ -103,6 +136,11 @@ ImageSequencer = function ImageSequencer(options) {
     return this;
   }
 
+  /**
+   * @method insertSteps
+   * @description Inserts steps at the specified index
+   * @returns {Object}
+   */
   function insertSteps() {
     var this_ = (this.name == 'ImageSequencer') ? this : this.sequencer;
     var args = [];
@@ -118,8 +156,11 @@ ImageSequencer = function ImageSequencer(options) {
     return this;
   }
 
-  // Config is an object which contains the runtime configuration like progress bar
-  // information and index from which the sequencer should run
+  /**
+   * @method run
+   * @param {Object} config Object which contains the runtime configuration like progress bar information and index from which the sequencer should run.
+   * @returns {Boolean}
+   */
   function run(config) {
     var progressObj, index = 0;
     config = config || { mode: 'no-arg' };
@@ -137,7 +178,7 @@ ImageSequencer = function ImageSequencer(options) {
     var callback = function() { };
     for (var arg in args)
       if (objTypeOf(args[arg]) == 'Function')
-        callback = args.splice(arg, 1)[0]; //callback is formed
+        callback = args.splice(arg, 1)[0]; // Callback is formed
 
     var json_q = formatInput.call(this_, args, 'r');
 
@@ -146,6 +187,11 @@ ImageSequencer = function ImageSequencer(options) {
     return true;
   }
 
+  /**
+   * @method loadImages
+   * @description Loads an image via dataURL or normal URL. Read the docs(https://github.com/publiclab/image-sequencer/blob/main/README.md) for more info.
+   * @returns {Null}
+   */
   function loadImages() {
     var args = [];
     var prevSteps = this.getSteps().slice(1).map(step=>step.options.name);
@@ -182,17 +228,35 @@ ImageSequencer = function ImageSequencer(options) {
 
   }
 
+  /**
+   * @method replaceImage
+   * @description Replaces the current image in the sequencer
+   * @param {String} selector DOM selector string for the image input
+   * @param {*} steps Current steps Object
+   * @param {Object} options
+   * @returns {*}
+   */
   function replaceImage(selector, steps, options) {
     options = options || {};
     options.callback = options.callback || function() { };
     return require('./ReplaceImage')(this, selector, steps, options);
   }
 
-  //returns the steps added
+  /**
+   * @method getSteps
+   * @description Returns the current sequence of steps
+   * @returns {Object}
+   */
   function getSteps(){
     return this.steps;
   }
 
+  /**
+   * @method setUI
+   * @description To set up a UI for ImageSequencer via different callback methods. Read the docs(https://github.com/publiclab/image-sequencer/blob/main/README.md) for more info.
+   * @param {Object} UI Object containing UI callback methods. Read the docs(https://github.com/publiclab/image-sequencer/blob/main/README.md) for more info.
+   * @returns {Null}
+   */
   function setUI(UI) {
     this.events = require('./ui/UserInterface')(UI);
   }
@@ -201,6 +265,12 @@ ImageSequencer = function ImageSequencer(options) {
     return require('./ExportBin')(dir, this, basic, filename);
   };
 
+  /**
+   * @method modulesInfo
+   * @description Returns information about the given module or all the available modules
+   * @param {String} name Module name
+   * @returns {Object}
+   */
   function modulesInfo(name) {
     var modulesdata = {};
     if (name == 'load-image') return {};
@@ -222,23 +292,30 @@ ImageSequencer = function ImageSequencer(options) {
     return modulesdata;
   }
 
+  /**
+   * @method loadNewModule
+   * @description Adds a new local module to sequencer. Read the docs(https://github.com/publiclab/image-sequencer/blob/main/README.md) for mode info.
+   * @param {String} name Name of the new module
+   * @param {Object} options An Object containing path and info about the new module.
+   * @returns {Object}
+   */
   function loadNewModule(name, options) {
 
     if (!options) {
       return this;
 
     } else if (Array.isArray(options)) {
-      // contains the array of module and info
+      // Contains the array of module and info
       this.modules[name] = options;
 
     } else if (options.func && options.info) {
-      // passed in options object
+      // Passed in options object
       this.modules[name] = [
         options.func, options.info
       ];
 
     } else if (options.path && !this.inBrowser) {
-      // load from path(only in node)
+      // Load from path(only in node)
       const module = [
         require(`${options.path}/Module.js`),
         require(`${options.path}/info.json`)
@@ -248,6 +325,13 @@ ImageSequencer = function ImageSequencer(options) {
     return this;
   }
 
+  /**
+   * @method saveNewModule
+   * @description Saves a new local module to ImageSequencer
+   * @param {String} name Name of the new module
+   * @param {String} path Path to the new module
+   * @returns {Null}
+   */
   function saveNewModule(name, path) {
     if (options.inBrowser) {
       // Not for browser context
@@ -258,6 +342,13 @@ ImageSequencer = function ImageSequencer(options) {
     fs.writeFileSync('./src/Modules.js', mods);
   }
 
+  /**
+   * @method saveSequence
+   * @description Saves a sequence on the browser localStorage.
+   * @param {String} name Name for the sequence
+   * @param {String} sequenceString Sequence data as a string
+   * @returns {Null}
+   */
   function saveSequence(name, sequenceString) { // 4. save sequence
     const sequence = str.stringToJSON(sequenceString);
     // Save the given sequence string as a module
@@ -276,7 +367,7 @@ ImageSequencer = function ImageSequencer(options) {
   }
 
   function loadModules() {
-    // This function loads the modules and saved sequences
+    // loadModules function loads the modules and saved sequences.
     this.modules = require('./Modules');
     if (options.inBrowser)
       this.sequences = JSON.parse(window.localStorage.getItem('sequences'));
@@ -286,7 +377,7 @@ ImageSequencer = function ImageSequencer(options) {
 
 
   return {
-    //literals and objects
+    // Literals and objects
     name: 'ImageSequencer',
     options: options,
     inputlog: inputlog,
@@ -296,7 +387,7 @@ ImageSequencer = function ImageSequencer(options) {
     steps: steps,
     image: image,
 
-    //user functions
+    // User functions
     loadImages: loadImages,
     loadImage: loadImages,
     addSteps: addSteps,
@@ -325,7 +416,7 @@ ImageSequencer = function ImageSequencer(options) {
     loadModules: loadModules,
     getSteps:getSteps,
 
-    //other functions
+    // Other functions
     log: log,
     objTypeOf: objTypeOf,
     copy: copy,

src/modules/_nomodule/PixelManipulation.js

@@ -2,6 +2,14 @@
  * General purpose per-pixel manipulation
  * accepting a changePixel() method to remix a pixel's channels
  */
+
+/**
+ * @method PixelManipulation
+ * @description Function for changing pixel values of the image via different callback functions. Read the docs(https://github.com/publiclab/image-sequencer/blob/main/CONTRIBUTING.md) for more info.
+ * @param {Object} image ndarray of pixels of the image
+ * @param {Object} options object containing callbacks for manipulating pixels.
+ * @returns {Null}
+ */
 module.exports = function PixelManipulation(image, options) {
   // To handle the case where pixelmanipulation is called on the input object itself
   // like input.pixelManipulation(options)
@@ -30,18 +38,18 @@ module.exports = function PixelManipulation(image, options) {
       };
     }
 
-    // iterate through pixels;
+    // Iterate through pixels
     // TODO: this could possibly be more efficient; see
     // https://github.com/p-v-o-s/infragram-js/blob/master/public/infragram.js#L173-L181
 
 
-    if (options.preProcess) pixels = options.preProcess(pixels); // Allow for preprocessing
+    if (options.preProcess) pixels = options.preProcess(pixels); // Allow for preprocessing of pixels.
 
     function extraOperation() {
       var res;
-      if (options.extraManipulation) res = options.extraManipulation(pixels, generateOutput);
-      // there may be a more efficient means to encode an image object,
-      // but node modules and their documentation are essentially arcane on this point
+      if (options.extraManipulation) res = options.extraManipulation(pixels, generateOutput); // extraManipulation is used to manipulate each pixel individually.
+      // There may be a more efficient means to encode an image object,
+      // but node modules and their documentation are essentially arcane on this point.
       function generateOutput() {
         var chunks = [];
         var totalLength = 0;
@@ -80,7 +88,7 @@ module.exports = function PixelManipulation(image, options) {
         env: {
           consoleLog: console.log,
           perform: function (x, y) {
-            let pixel = options.changePixel(
+            let pixel = options.changePixel( // changePixel function is run over every pixel.
               pixels.get(x, y, 0),
               pixels.get(x, y, 1),
               pixels.get(x, y, 2),
@@ -95,7 +103,7 @@ module.exports = function PixelManipulation(image, options) {
         }
       };
 
-      function perPixelManipulation() { // pure JavaScript code
+      function perPixelManipulation() {
         for (var x = 0; x < pixels.shape[0]; x++) {
           for (var y = 0; y < pixels.shape[1]; y++) {
             imports.env.perform(x, y);
@@ -145,4 +153,4 @@ module.exports = function PixelManipulation(image, options) {
       }
     }
   });
-};
+};