Patchwork GenerateDocstring PR

public/bower_components/core-focusable/core-focusable.js

@@ -77,6 +77,9 @@ Polymer.CoreFocusable = {
     disabled: '_disabledChanged'
   },
 
+  /**
+   * Handles changes in the disabled state of the component. If the component is disabled it stops pointer events, removes tabindex, and set aria-disabled attribute. Conversely, if the component is enabled it allows pointer events, adds tabindex, and removes aria-disabled attribute.
+   */
   _disabledChanged: function() {
     if (this.disabled) {
       this.style.pointerEvents = 'none';
@@ -89,6 +92,10 @@ Polymer.CoreFocusable = {
     }
   },
 
+  /**
+   * Function to handle the downAction which alters the active and pressed states. When invoked, sets the status of 'pressed' as true. If 'toggle' is true, it inverts the status of 'active'; otherwise, sets 'active' as true.
+   */
+
   _downAction: function() {
     this.pressed = true;
 
@@ -111,6 +118,11 @@ Polymer.CoreFocusable = {
     this._focusAction();
   },
 
+  /**
+   * Method to handle the up action. It is used to manage the state of a potentially toggleable button or input. 
+   * If the toggle property of the button or input is false, it turns off its active state upon triggering up action.
+   * @returns {void} This method does not return anything.
+   */
   _upAction: function() {
     this.pressed = false;
 
@@ -119,6 +131,11 @@ Polymer.CoreFocusable = {
     }
   },
 
+  /**
+   * Represents a method that sets the 'focused' state of the element to true only when the element is not in a 'pressed' state. 
+   * Primarily used for keyboard-based navigation.
+   * @returns {void} This method does not have a return value.
+   */
   _focusAction: function() {
     if (!this.pressed) {
       // Only render the "focused" state if the element gains focus due to
@@ -127,6 +144,10 @@ Polymer.CoreFocusable = {
     }
   },
 
+  /**
+   * This method is responsible for managing the blur action within the application. Upon calling it, it alters the application focus state.
+   * @returns {void} No directly observable return value. The focused state of the application is internally altered to false. 
+   */
   _blurAction: function() {
     this.focused = false;
   }

public/bower_components/core-focusable/polymer-mixin.js

@@ -1,3 +1,9 @@
+/**
+ * This method is for handling the mixture of prototypes. It adds properties from a mixin to a prototype, including publish, eventDelegates, and observe properties.
+ * @param {Object} prototype - The prototype object that is being extended.
+ * @param {Object} mixin - The mixin object that contains properties to add to the prototype.
+ * @returns {Object} Returns the updated prototype object.
+ */
 Polymer.mixin2 = function(prototype, mixin) {
 
   // adds a single mixin to prototype

public/bower_components/core-overlay/tests/js/htmltests.js

@@ -1,7 +1,18 @@
-htmlSuite('core-overlay', function() {
-  htmlTest('html/core-overlay-basic.html');
-  htmlTest('html/core-overlay-positioning.html');
-  htmlTest('html/core-overlay-positioning-margin.html');
-  htmlTest('html/core-overlay-scroll.html');
-  htmlTest('html/core-overlay-quick-close.html');
-});
+/**
+ * This method is a suite of tests for the 'core-overlay' functionality. Each separate test is described by the string input parameter, 
+ * which represents the specific HTML file that contains the test. The core-overlay functionality is likely a UI element or group of 
+ * elements, and these tests verify its correct operation and interaction with other elements.
+ * @param {string} 'html/core-overlay-basic.html' - The path to the basic test for core-overlay functionality.
+ * @param {string} 'html/core-overlay-positioning.html' - The path to the test for the positioning of the core-overlay.
+ * @param {string} 'html/core-overlay-positioning-margin.html' - The path to the test for the positioning margin of the core-overlay.
+ * @param {string} 'html/core-overlay-scroll.html' - The path to the test for the scrolling feature of the core-overlay.
+ * @param {string} 'html/core-overlay-quick-close.html' - The path to the test for the quick close feature of the core-overlay.
+ * @returns {void} This function does not return anything. It simply runs the tests as indicated by the argument paths.
+ */
+htmlSuite('core-overlay', function() {
+  htmlTest('html/core-overlay-basic.html');
+  htmlTest('html/core-overlay-positioning.html');
+  htmlTest('html/core-overlay-positioning-margin.html');
+  htmlTest('html/core-overlay-scroll.html');
+  htmlTest('html/core-overlay-quick-close.html');
+});

public/bower_components/file-input/file-input.js

@@ -1,8 +1,77 @@
+/**
+ * Represents a collection of helper methods used to process and validate file inputs.
+ */
+
+/**
+ * Converts a pseudoArray into an array.
+ * @param {Object} pseudoArray - The object that needs to be converted into an array.
+ * @returns {Array} The converted object in array form.
+ */
+
+/**
+ * Extracts the lower case extension from a given filename.
+ * @param {string} filename - The name of the file.
+ * @returns {string} The lower case extension of the file.
+ */
+
+/**
+ * Process and validates the limit of the count of the files.
+ * @param {number} limit - Maximum limit for files.
+ * @param {Array} files - Array of file objects.
+ * @returns {Object} An object containing two arrays: 'invalid' with files that exceed the limit, and 'valid' with the files within the limit.
+ */
+
+/**
+ * Validates the file extension against a string of permissible extensions.
+ * @param {string} extensionsStr - JSON String containing valid extensions.
+ * @param {Array} files - Array of file objects to validate against extensions.
+ * @returns {Object} An object containing two arrays: 'invalid' with the files having non-permissible extensions, and 'valid' with the valid files.
+ */
+
+/**
+ * Validates the size of the files.
+ * @param {number} minSize - Minimum size allowed for files.
+ * @param {number} maxSize - Maximum size allowed for files.
+ * @param {Array} files - Array of file objects to validate file sizes.
+ * @returns {Object} An object containing three arrays: 'tooBig' for files larger than maxSize, 'tooSmall' for files smaller than minSize, and 'valid' for correctly sized files.
+ */
+
+/**
+ * Checks if the current device is an iOS device.
+ * @returns {boolean} True if the device is an iOS device, else False.
+ */
+
+/**
+ * Resets the input field without disconnecting it from its Parent Node.
+ * @param {Object} customEl - Custom Element 
+ */
+
+/**
+ * Sets up a hidden validation input field.
+ * @param {Object} customEl - Custom Element 
+ */
+
+
+/**
+ * Updates the validity of the file input depending on whether files are selected or not.
+ * @param {Object} customEl - Custom Element 
+ */
+
 (function() {
+    /**
+     * This method converts pseudocode array to a proper JavaScript array.
+     * @param {Array-like object} pseudoArray - An array-like object for conversion.
+     * @returns {Array} Converted JavaScript array.
+     */
     var arrayOf = function(pseudoArray) {
             return Array.prototype.slice.call(pseudoArray);
         },
 
+        /**
+         * This method is used to obtain the lowercase extension from a given filename.
+         * @param {String} filename - The name of the file from which the extension is to be extracted.
+         * @returns {String} The lowercase file extension part from the input filename. If the filename does not contain any extension, it will return undefined.
+         */
         getLowerCaseExtension = function(filename) {
             var extIdx = filename.lastIndexOf(".") + 1;
 
@@ -11,6 +80,13 @@
             }
         },
 
+        /**
+         * This function validates if the provided limit criteria is met by comparing it to the number of files. 
+         * It then separates the invalid and valid files.
+         * @param {Number} limit - User-defined limit specifying the maximum number of files that are considered valid.
+         * @param {Array} files - Array containing all the files that need to be validated.
+         * @returns {Object} An object with two properties: 'invalid', an array of files that exceed the limit, and 'valid', an array of files that are within the limit.
+         */
         getResultOfCountLimitValidation = function(limit, files) {
             if (limit > 0 && limit < files.length) {
                 return {
@@ -22,12 +98,33 @@
             return {invalid: [], valid: files};
         },
 
+        /**
+         * Function to validate file extensions against a list of allowed (or disallowed) extensions.
+         * The function parses a JSON formatted list of extensions and checks each file in provided files array. 
+         * It groups the files into valid and invalid based on their extension.
+         * If 'extensionsStr' begins with '!', the provided extensions are deemed as invalid. Files matching these are grouped in 'invalid'.
+         * If 'extensionsStr' doesn't begin with '!', the provided extensions are deemed as valid, Files matching these are grouped in 'valid'.
+         * 
+         * @param {string}  extensionsStr - A JSON formatted string of extensions to validate files against.
+         * @param {Array}  files - An array of files to validate, each file is an object with a 'name' property.
+         * @returns {Object} An object containing two arrays - 'valid' and 'invalid', housing files based on the result of validation.
+         */
         getResultOfExtensionsValidation = function(extensionsStr, files) {
             if (extensionsStr) {
                 var negate = extensionsStr.charAt(0) === "!",
                     extensions = JSON.parse(extensionsStr.toLowerCase().substr(negate ? 1 : 0)),
                     result = {invalid: [], valid: []};
 
+                /**
+                 * Iterates over each file in the 'files' array, determines the file extension, and categorizes 
+                 * it as either 'valid' or 'invalid' based on whether the extension is found within the 'extensions' array. 
+                 * The categorization is flipped if 'negate' is true.
+                 * @param {Array}  files - An array of file objects which should at least contain a 'name' property.
+                 * @param {string} file.name - The name of the file from which the extension is extracted.
+                 * @param {boolean}  negate - Optional boolean flag indicating if the check should be negated, default is 'false'.
+                 * @param {Array}  extensions - Array of file extensions considered valid.
+                 * @returns {Object} An object with two properties: 'valid' and 'invalid'. Each one is an array containing the files which passed or failed the check.
+                 */
                 files.forEach(function(file) {
                     var extension = getLowerCaseExtension(file.name);
 
@@ -45,6 +142,13 @@
             return {invalid: [], valid: files};
         },
 
+        /**
+         * This method validates the size of each file in a list of files, categorizing them into too big, too small, and valid groups.
+         * @param {Number} minSize - The minimum file size limit. If this parameter is false, there is no lower limit.
+         * @param {Number} maxSize - The maximum file size limit. If this parameter is false, there is no upper limit.
+         * @param {Array} files - Array of file objects which should contain at least a size property.
+         * @returns {Object} An object containing three properties: tooBig (containing files that are too big), tooSmall (containing files that are too small), and valid (containing files that fall within the size limits).
+         */
         getResultOfSizeValidation = function(minSize, maxSize, files) {
             if (!minSize && !maxSize) {
                 return {tooBig: [], tooSmall: [], valid: files};
@@ -54,6 +158,15 @@
                 tooBig = [],
                 tooSmall = [];
 
+            /**
+             * Processes each file in the files array. If a file size is less than minSize, it pushes it into the tooSmall array. 
+             * If a file size is greater than maxSize, it pushes it into the tooBig array. 
+             * Whenever a file size is in between minSize and maxSize or either of these is undefined, it pushes the file into the valid array. 
+             * @param {Object[]} files - An array of file objects to be processed
+             * @param {number} minSize - The smallest acceptable file size. If no minimum size is required, this should be null or undefined.
+             * @param {number} maxSize - The largest acceptable file size. If no maximum size is required, this should be null or undefined.
+             * @returns {void} This function does not return a value. The arrays tooSmall, tooBig, and valid are modified by this function.
+             */
             files.forEach(function(file) {
                 if (minSize && file.size < minSize) {
                     tooSmall.push(file);
@@ -69,6 +182,10 @@
             return {tooBig: tooBig, tooSmall: tooSmall, valid: valid};
         },
 
+        /**
+         * Evaluates the user's navigator agent string for keywords related to iOS devices ("iPad", "iPod", "iPhone").
+         * @returns {boolean} True if the user's navigator agent contains any of the listed iOS device keywords, false otherwise.
+         */
         isIos = function() {
             return navigator.userAgent.indexOf("iPad") !== -1 ||
                 navigator.userAgent.indexOf("iPod") !== -1 ||
@@ -101,6 +218,11 @@
             updateValidity(customEl);
         },
 
+        /**
+         * Sets up a validation target by creating a new input element and setting various styles and attributes. A reference to a custom element is attached to the newly created input. The input is added to the DOM before the custom element and makes a call to update the validity of the custom element.
+         * @param {Element} customEl - The custom element to which the validation target corresponds.
+         * @returns {void}
+         */
         setupValidationTarget = function(customEl) {
             validationTarget = document.createElement("input");
             validationTarget.setAttribute("tabindex", "-1");
@@ -126,6 +248,12 @@
             updateValidity(customEl);
         },
 
+        /**
+         * This method updates the validity of the provided custom element within a validation target.
+         * If the custom element has a file(s), it sets the validation target's custom validity to an empty string.
+         * If the custom element does not have a file, it sets the custom validity of the validation target to the invalidText of the provided custom element.
+         * @param {Object} customEl - The custom element whose validity is to be checked. It must contain a property 'files' (Array) and 'invalidText' (String). 
+         */
         updateValidity = function(customEl) {
             if (validationTarget) {
                 if (customEl.files.length) {
@@ -141,6 +269,12 @@
 
 
    this.fileInput = {
+        /**
+         * Handles changes in the file input by validating the selected files based on various provided constraints like minimum and maximum file size, 
+         * allowed file extensions, and maximum number of files. If a file fails in any of the constraints, it is added to an invalid files list with the 
+         * specific reason for being invalid. Valid files are stored separately and both lists (invalid and valid files) are updated in the element's state. 
+         * Updates the component's validation status and emits a 'change' event with the current state of invalid and valid selected files.
+         */
         changeHandler: function() {
             var customEl = this,
                 files = arrayOf(customEl.$.fileInput.files),
@@ -182,6 +316,10 @@
             }
         },
 
+        /**
+         * This method is automatically executed when the component instance has been created, 
+         * and is used to initialize the 'files' array and the 'invalid' object.
+         */
         created: function() {
             var customEl = this;
 
@@ -197,6 +335,12 @@
 
         minSize: 0,
 
+        /**
+         * Sets up the domReady function. Adjusts camera settings on iOS devices, handles file input properties based on set parameters, and sets validation if needed.
+         * @function domReady
+         * @param {Object}  customEl - The custom element the function is operating on.
+         * @returns {void} - Does not return anything.
+         */
         domReady: function() {
             var customEl = this;
 
@@ -225,6 +369,10 @@
             }
         },
 
+        /**
+         * Resets the custom element by reinitializing it and resetting its input.
+         * @returns {void} Nothing
+         */
         reset: function() {
             var customEl = this;
 

public/bower_components/file-input/gruntfile.js

@@ -3,6 +3,11 @@ function config(name) {
     return require("./grunt_tasks/" + name + ".js");
 }
 
+/**
+ * This function is used to initialize grunt tasks and register new tasks.
+ * @param {Object} grunt - Grunt is a task-based command-line build tool for JavaScript projects.
+ * There are no explicit returns, but it has an implicit return of `undefined` if the function completes without early return.
+ */
 module.exports = function(grunt) {
     grunt.initConfig({
         pkg: grunt.file.readJSON("package.json"),