diff --git a/.jscsrc b/.jscsrc index 3a257454..4888c20e 100644 --- a/.jscsrc +++ b/.jscsrc @@ -5,6 +5,18 @@ "validateIndentation": 2, "excludeFiles": ["node_modules/**"], "maximumLineLength": 130, - "requireCamelCaseOrUpperCaseIdentifiers": true, - "validateQuoteMarks": "'" + "validateQuoteMarks": "'", + "requireCamelCaseOrUpperCaseIdentifiers": null, + "additionalRules": ["utils/jscs-rules/*.js"], + "closureCamelCase": true, + "jsDoc": { + "checkAnnotations": { + "preset": "closurecompiler", + "extra": { + "type": true + } + }, + "checkTypes": "strictNativeCase", + "enforceExistence": "exceptExports" + } } diff --git a/gulpfile.js b/gulpfile.js index 771d6388..813c6d15 100644 --- a/gulpfile.js +++ b/gulpfile.js @@ -362,6 +362,9 @@ gulp.task('demoresources', function() { * put together. */ gulp.task('demos', ['demoresources'], function() { + /** + * Retrieves the list of component folders. + */ function getComponentFolders() { return fs.readdirSync('./src/') .filter(function(file) { @@ -444,6 +447,9 @@ gulp.task('assets', function() { .pipe(gulp.dest('dist/assets')); }); +/** + * Defines the list of resources to watch for changes. + */ function watch() { gulp.watch(['src/**/*.js', '!src/**/README.md'], ['scripts', 'demos', 'components', reload]); @@ -566,8 +572,11 @@ gulp.task('publish:code', function(cb) { cb); }); -// Function to publish staging or prod version from local tree, -// or to promote staging to prod, per passed arg. +/** + * Function to publish staging or prod version from local tree, + * or to promote staging to prod, per passed arg. + * @param {string} pubScope the scope to publish to. + */ function mdlPublish(pubScope) { var cacheTtl = null; var src = null; diff --git a/package.json b/package.json index 71ea8c77..791a6a8e 100644 --- a/package.json +++ b/package.json @@ -32,7 +32,7 @@ "gulp-if": "^1.2.1", "gulp-iife": "0.0.7", "gulp-imagemin": "^2.2.1", - "gulp-jscs": "^1.6.0", + "gulp-jscs": "^2.0.0", "gulp-jshint": "^1.6.3", "gulp-load-plugins": "^0.10.0", "gulp-markdown": "^1.0.0", diff --git a/src/button/button.js b/src/button/button.js index 0e8fd9aa..f3f660bc 100644 --- a/src/button/button.js +++ b/src/button/button.js @@ -36,7 +36,7 @@ /** * Store constants in one place so they can be updated easily. * - * @enum {String | Number} + * @enum {string | number} * @private */ MaterialButton.prototype.Constant_ = { @@ -48,7 +48,7 @@ * JavaScript. This allows us to simply change it in one place should we * decide to modify at a later date. * - * @enum {String} + * @enum {string} * @private */ MaterialButton.prototype.CssClasses_ = { diff --git a/src/checkbox/checkbox.js b/src/checkbox/checkbox.js index 9e0ea102..46988878 100644 --- a/src/checkbox/checkbox.js +++ b/src/checkbox/checkbox.js @@ -23,6 +23,7 @@ * Implements MDL component design pattern defined at: * https://github.com/jasonmayes/mdl-component-design-pattern * + * @constructor * @param {HTMLElement} element The element that will be upgraded. */ var MaterialCheckbox = function MaterialCheckbox(element) { @@ -36,7 +37,7 @@ /** * Store constants in one place so they can be updated easily. * - * @enum {String | Number} + * @enum {string | number} * @private */ MaterialCheckbox.prototype.Constant_ = { @@ -48,7 +49,7 @@ * JavaScript. This allows us to simply change it in one place should we * decide to modify at a later date. * - * @enum {String} + * @enum {string} * @private */ MaterialCheckbox.prototype.CssClasses_ = { @@ -120,15 +121,14 @@ /** * Add blur. * - * @param {Event} event The event that fired. * @private */ - MaterialCheckbox.prototype.blur_ = function(event) { + MaterialCheckbox.prototype.blur_ = function() { // TODO: figure out why there's a focus event being fired after our blur, // so that we can avoid this hack. window.setTimeout(function() { this.inputElement_.blur(); - }.bind(this), this.Constant_.TINY_TIMEOUT); + }.bind(this), /** @type {number} */ (this.Constant_.TINY_TIMEOUT)); }; // Public methods. diff --git a/src/data-table/data-table.js b/src/data-table/data-table.js index 56133d9f..45a80825 100644 --- a/src/data-table/data-table.js +++ b/src/data-table/data-table.js @@ -23,6 +23,7 @@ * Implements MDL component design pattern defined at: * https://github.com/jasonmayes/mdl-component-design-pattern * + * @constructor * @param {HTMLElement} element The element that will be upgraded. */ var MaterialDataTable = function MaterialDataTable(element) { @@ -31,12 +32,13 @@ // Initialize instance. this.init(); }; + window.MaterialDataTable = MaterialDataTable; /** * Store constants in one place so they can be updated easily. * - * @enum {String | Number} + * @enum {string | number} * @private */ MaterialDataTable.prototype.Constant_ = { @@ -48,7 +50,7 @@ * JavaScript. This allows us to simply change it in one place should we * decide to modify at a later date. * - * @enum {String} + * @enum {string} * @private */ MaterialDataTable.prototype.CssClasses_ = { @@ -62,12 +64,12 @@ * Generates and returns a function that toggles the selection state of a * single row (or multiple rows). * - * @param {HTMLElement} checkbox Checkbox that toggles the selection state. + * @param {Element} checkbox Checkbox that toggles the selection state. * @param {HTMLElement} row Row to toggle when checkbox changes. - * @param {HTMLElement[]} rows Rows to toggle when checkbox changes. + * @param {NodeList=} opt_rows Rows to toggle when checkbox changes. * @private */ - MaterialDataTable.prototype.selectRow_ = function(checkbox, row, rows) { + MaterialDataTable.prototype.selectRow_ = function(checkbox, row, opt_rows) { if (row) { return function() { if (checkbox.checked) { @@ -78,21 +80,21 @@ }.bind(this); } - if (rows) { + if (opt_rows) { return function() { var i; var el; if (checkbox.checked) { - for (i = 0; i < rows.length; i++) { - el = rows[i].querySelector('td').querySelector('.mdl-checkbox'); + for (i = 0; i < opt_rows.length; i++) { + el = opt_rows[i].querySelector('td').querySelector('.mdl-checkbox'); el.MaterialCheckbox.check(); - rows[i].classList.add(this.CssClasses_.IS_SELECTED); + opt_rows[i].classList.add(this.CssClasses_.IS_SELECTED); } } else { - for (i = 0; i < rows.length; i++) { - el = rows[i].querySelector('td').querySelector('.mdl-checkbox'); + for (i = 0; i < opt_rows.length; i++) { + el = opt_rows[i].querySelector('td').querySelector('.mdl-checkbox'); el.MaterialCheckbox.uncheck(); - rows[i].classList.remove(this.CssClasses_.IS_SELECTED); + opt_rows[i].classList.remove(this.CssClasses_.IS_SELECTED); } } }.bind(this); @@ -104,10 +106,10 @@ * event handling. * * @param {HTMLElement} row Row to toggle when checkbox changes. - * @param {HTMLElement[]} rows Rows to toggle when checkbox changes. + * @param {NodeList=} opt_rows Rows to toggle when checkbox changes. * @private */ - MaterialDataTable.prototype.createCheckbox_ = function(row, rows) { + MaterialDataTable.prototype.createCheckbox_ = function(row, opt_rows) { var label = document.createElement('label'); label.classList.add('mdl-checkbox'); label.classList.add('mdl-js-checkbox'); @@ -118,9 +120,11 @@ checkbox.classList.add('mdl-checkbox__input'); if (row) { checkbox.addEventListener('change', this.selectRow_(checkbox, row)); - } else if (rows) { - checkbox.addEventListener('change', this.selectRow_(checkbox, null, rows)); + } else if (opt_rows) { + checkbox.addEventListener('change', + this.selectRow_(checkbox, null, opt_rows)); } + label.appendChild(checkbox); componentHandler.upgradeElement(label, 'MaterialCheckbox'); return label; diff --git a/src/icon-toggle/icon-toggle.js b/src/icon-toggle/icon-toggle.js index be9ad0c7..a0246b27 100644 --- a/src/icon-toggle/icon-toggle.js +++ b/src/icon-toggle/icon-toggle.js @@ -23,6 +23,7 @@ * Implements MDL component design pattern defined at: * https://github.com/jasonmayes/mdl-component-design-pattern * + * @constructor * @param {HTMLElement} element The element that will be upgraded. */ var MaterialIconToggle = function MaterialIconToggle(element) { @@ -36,7 +37,7 @@ /** * Store constants in one place so they can be updated easily. * - * @enum {String | Number} + * @enum {string | number} * @private */ MaterialIconToggle.prototype.Constant_ = { @@ -48,7 +49,7 @@ * JavaScript. This allows us to simply change it in one place should we * decide to modify at a later date. * - * @enum {String} + * @enum {string} * @private */ MaterialIconToggle.prototype.CssClasses_ = { @@ -116,15 +117,14 @@ /** * Add blur. * - * @param {Event} event The event that fired. * @private */ - MaterialIconToggle.prototype.blur_ = function(event) { + MaterialIconToggle.prototype.blur_ = function() { // TODO: figure out why there's a focus event being fired after our blur, // so that we can avoid this hack. window.setTimeout(function() { this.inputElement_.blur(); - }.bind(this), this.Constant_.TINY_TIMEOUT); + }.bind(this), /** @type {number} */ (this.Constant_.TINY_TIMEOUT)); }; // Public methods. diff --git a/src/layout/layout.js b/src/layout/layout.js index 34c2f395..bec2bade 100644 --- a/src/layout/layout.js +++ b/src/layout/layout.js @@ -23,6 +23,7 @@ * Implements MDL component design pattern defined at: * https://github.com/jasonmayes/mdl-component-design-pattern * + * @constructor * @param {HTMLElement} element The element that will be upgraded. */ var MaterialLayout = function MaterialLayout(element) { @@ -36,7 +37,7 @@ /** * Store constants in one place so they can be updated easily. * - * @enum {String | Number} + * @enum {string | number} * @private */ MaterialLayout.prototype.Constant_ = { @@ -51,7 +52,7 @@ /** * Modes. * - * @enum {Number} + * @enum {number} * @private */ MaterialLayout.prototype.Mode_ = { @@ -66,7 +67,7 @@ * JavaScript. This allows us to simply change it in one place should we * decide to modify at a later date. * - * @enum {String} + * @enum {string} * @private */ MaterialLayout.prototype.CssClasses_ = { @@ -244,7 +245,8 @@ // Keep an eye on screen size, and add/remove auxiliary class for styling // of small screens. - this.screenSizeMediaQuery_ = window.matchMedia(this.Constant_.MAX_WIDTH); + this.screenSizeMediaQuery_ = window.matchMedia( + /** @type {string} */ (this.Constant_.MAX_WIDTH)); this.screenSizeMediaQuery_.addListener(this.screenSizeHandler_.bind(this)); this.screenSizeHandler_(); @@ -284,6 +286,10 @@ } } + /** + * Prevents an event from triggering the default behaviour. + * @param {Event} ev the event to eat. + */ var eatEvent = function(ev) { ev.preventDefault(); }; @@ -402,6 +408,15 @@ } }; + /** + * Constructor for an individual tab. + * + * @constructor + * @param {HTMLElement} tab The HTML element for the tab. + * @param {!Array} tabs Array with HTML elements for all tabs. + * @param {!Array} panels Array with HTML elements for all panels. + * @param {MaterialLayout} layout The MaterialLayout object that owns the tab. + */ function MaterialLayoutTab(tab, tabs, panels, layout) { if (tab) { if (layout.tabBar_.classList.contains( diff --git a/src/mdlComponentHandler.js b/src/mdlComponentHandler.js index 5f2b777a..3630010b 100644 --- a/src/mdlComponentHandler.js +++ b/src/mdlComponentHandler.js @@ -39,15 +39,15 @@ window.componentHandler = (function() { * Searches registered components for a class we are interested in using. * Optionally replaces a match with passed object if specified. * - * @param {String} name The name of a class we want to use. + * @param {string} name The name of a class we want to use. * @param {componentHandler.ComponentConfig=} optReplace Optional object to replace match with. - * @return {!Object|Boolean} + * @return {!Object|boolean} * @private */ function findRegisteredClass_(name, optReplace) { for (var i = 0; i < registeredComponents_.length; i++) { if (registeredComponents_[i].className === name) { - if (optReplace !== undefined) { + if (typeof optReplace !== 'undefined') { registeredComponents_[i] = optReplace; } return registeredComponents_[i]; @@ -60,7 +60,7 @@ window.componentHandler = (function() { * Returns an array of the classNames of the upgraded classes on the element. * * @param {!HTMLElement} element The element to fetch data from. - * @return {!Array} + * @return {!Array} * @private */ function getUpgradedListOfElement_(element) { @@ -74,8 +74,8 @@ window.componentHandler = (function() { * class. * * @param {!HTMLElement} element The element we want to check. - * @param {String} jsClass The class to check for. - * @returns {Boolean} + * @param {string} jsClass The class to check for. + * @returns {boolean} * @private */ function isElementUpgraded_(element, jsClass) { @@ -87,20 +87,21 @@ window.componentHandler = (function() { * Searches existing DOM for elements of our component type and upgrades them * if they have not already been upgraded. * - * @param {String=} optJsClass the programatic name of the element class we + * @param {string=} optJsClass the programatic name of the element class we * need to create a new instance of. - * @param {String=} optCssClass the name of the CSS class elements of this + * @param {string=} optCssClass the name of the CSS class elements of this * type will have. */ function upgradeDomInternal(optJsClass, optCssClass) { - if (optJsClass === undefined && optCssClass === undefined) { + if (typeof optJsClass === 'undefined' && + typeof optCssClass === 'undefined') { for (var i = 0; i < registeredComponents_.length; i++) { upgradeDomInternal(registeredComponents_[i].className, registeredComponents_[i].cssClass); } } else { - var jsClass = /** @type {String} */ (optJsClass); - if (optCssClass === undefined) { + var jsClass = /** @type {string} */ (optJsClass); + if (typeof optCssClass === 'undefined') { var registeredClass = findRegisteredClass_(jsClass); if (registeredClass) { optCssClass = registeredClass.cssClass; @@ -118,7 +119,7 @@ window.componentHandler = (function() { * Upgrades a specific element rather than all in the DOM. * * @param {!HTMLElement} element The element we wish to upgrade. - * @param {String=} optJsClass Optional name of the class we want to upgrade + * @param {string=} optJsClass Optional name of the class we want to upgrade * the element to. */ function upgradeElementInternal(element, optJsClass) { @@ -202,7 +203,7 @@ window.componentHandler = (function() { /** * Registers a class for future use and attempts to upgrade existing DOM. * - * @param {{constructor: !Function, classAsString: String, cssClass: String, widget: String}} config + * @param {{constructor: !Function, classAsString: string, cssClass: string, widget: string}} config */ function registerInternal(config) { var newConfig = /** @type {componentHandler.ComponentConfig} */ ({ @@ -240,7 +241,7 @@ window.componentHandler = (function() { * Allows user to be alerted to any upgrades that are performed for a given * component type * - * @param {String} jsClass The class name of the MDL component we wish + * @param {string} jsClass The class name of the MDL component we wish * to hook into for any upgrades performed. * @param {function(!HTMLElement)} callback The function to call upon an * upgrade. This function should expect 1 parameter - the HTMLElement which @@ -312,6 +313,10 @@ window.componentHandler = (function() { * @param {!Node|!Array|!NodeList} nodes */ function downgradeNodesInternal(nodes) { + /** + * Auxiliary function to downgrade a single node. + * @param {!Node} node the node to be downgraded + */ var downgradeNode = function(node) { deconstructComponentInternal(findCreatedComponentByNodeInternal(node)); }; @@ -353,8 +358,14 @@ window.addEventListener('load', function() { document.documentElement.classList.add('mdl-js'); componentHandler.upgradeAllRegistered(); } else { - componentHandler.upgradeElement = - componentHandler.register = function() {}; + /** + * Dummy function to avoid JS errors. + */ + componentHandler.upgradeElement = function() {}; + /** + * Dummy function to avoid JS errors. + */ + componentHandler.register = function() {}; } }); @@ -364,9 +375,9 @@ window.addEventListener('load', function() { * * @typedef {{ * constructor: !Function, - * className: String, - * cssClass: String, - * widget: String, + * className: string, + * cssClass: string, + * widget: string, * callbacks: !Array * }} */ @@ -378,10 +389,10 @@ componentHandler.ComponentConfig; // jshint ignore:line * * @typedef {{ * element_: !HTMLElement, - * className: String, - * classAsString: String, - * cssClass: String, - * widget: String + * className: string, + * classAsString: string, + * cssClass: string, + * widget: string * }} */ componentHandler.Component; // jshint ignore:line diff --git a/src/menu/menu.js b/src/menu/menu.js index a1682340..9c211b9d 100644 --- a/src/menu/menu.js +++ b/src/menu/menu.js @@ -23,6 +23,7 @@ * Implements MDL component design pattern defined at: * https://github.com/jasonmayes/mdl-component-design-pattern * + * @constructor * @param {HTMLElement} element The element that will be upgraded. */ var MaterialMenu = function MaterialMenu(element) { @@ -36,7 +37,7 @@ /** * Store constants in one place so they can be updated easily. * - * @enum {String | Number} + * @enum {string | number} * @private */ MaterialMenu.prototype.Constant_ = { @@ -52,7 +53,7 @@ /** * Keycodes, for code readability. * - * @enum {Number} + * @enum {number} * @private */ MaterialMenu.prototype.Keycodes_ = { @@ -68,7 +69,7 @@ * JavaScript. This allows us to simply change it in one place should we * decide to modify at a later date. * - * @enum {String} + * @enum {string} * @private */ MaterialMenu.prototype.CssClasses_ = { @@ -301,7 +302,7 @@ window.setTimeout(function(evt) { this.hide(); this.closing_ = false; - }.bind(this), this.Constant_.CLOSE_TIMEOUT); + }.bind(this), /** @type {number} */ (this.Constant_.CLOSE_TIMEOUT)); } }; @@ -310,14 +311,14 @@ * it), and applies it. This allows us to animate from or to the correct point, * that is, the point it's aligned to in the "for" element. * - * @param {Number} height Height of the clip rectangle - * @param {Number} width Width of the clip rectangle + * @param {number} height Height of the clip rectangle + * @param {number} width Width of the clip rectangle * @private */ MaterialMenu.prototype.applyClip_ = function(height, width) { if (this.element_.classList.contains(this.CssClasses_.UNALIGNED)) { // Do not clip. - this.element_.style.clip = null; + this.element_.style.clip = ''; } else if (this.element_.classList.contains(this.CssClasses_.BOTTOM_RIGHT)) { // Clip to the top right corner of the menu. this.element_.style.clip = @@ -332,7 +333,7 @@ height + 'px ' + width + 'px)'; } else { // Default: do not clip (same as clipping to the top left corner). - this.element_.style.clip = null; + this.element_.style.clip = ''; } }; diff --git a/src/progress/progress.js b/src/progress/progress.js index efd4cb06..cd9f1e59 100644 --- a/src/progress/progress.js +++ b/src/progress/progress.js @@ -23,6 +23,7 @@ * Implements MDL component design pattern defined at: * https://github.com/jasonmayes/mdl-component-design-pattern * + * @constructor * @param {HTMLElement} element The element that will be upgraded. */ var MaterialProgress = function MaterialProgress(element) { @@ -36,7 +37,7 @@ /** * Store constants in one place so they can be updated easily. * - * @enum {String | Number} + * @enum {string | number} * @private */ MaterialProgress.prototype.Constant_ = { @@ -47,7 +48,7 @@ * JavaScript. This allows us to simply change it in one place should we * decide to modify at a later date. * - * @enum {String} + * @enum {string} * @private */ MaterialProgress.prototype.CssClasses_ = { @@ -57,7 +58,7 @@ /** * Set the current progress of the progressbar. * - * @param {Number} p Percentage of the progress (0-100) + * @param {number} p Percentage of the progress (0-100) * @public */ MaterialProgress.prototype.setProgress = function(p) { @@ -71,7 +72,7 @@ /** * Set the current progress of the buffer. * - * @param {Number} p Percentage of the buffer (0-100) + * @param {number} p Percentage of the buffer (0-100) * @public */ MaterialProgress.prototype.setBuffer = function(p) { diff --git a/src/radio/radio.js b/src/radio/radio.js index 72ddce75..972a69bb 100644 --- a/src/radio/radio.js +++ b/src/radio/radio.js @@ -23,6 +23,7 @@ * Implements MDL component design pattern defined at: * https://github.com/jasonmayes/mdl-component-design-pattern * + * @constructor * @param {HTMLElement} element The element that will be upgraded. */ var MaterialRadio = function MaterialRadio(element) { @@ -36,7 +37,7 @@ /** * Store constants in one place so they can be updated easily. * - * @enum {String | Number} + * @enum {string | number} * @private */ MaterialRadio.prototype.Constant_ = { @@ -48,7 +49,7 @@ * JavaScript. This allows us to simply change it in one place should we * decide to modify at a later date. * - * @enum {String} + * @enum {string} * @private */ MaterialRadio.prototype.CssClasses_ = { @@ -129,16 +130,15 @@ /** * Add blur. * - * @param {Event} event The event that fired. * @private */ - MaterialRadio.prototype.blur_ = function(event) { + MaterialRadio.prototype.blur_ = function() { // TODO: figure out why there's a focus event being fired after our blur, // so that we can avoid this hack. window.setTimeout(function() { this.btnElement_.blur(); - }.bind(this), this.Constant_.TINY_TIMEOUT); + }.bind(this), /** @type {number} */ (this.Constant_.TINY_TIMEOUT)); }; // Public methods. diff --git a/src/ripple/ripple.js b/src/ripple/ripple.js index 3aae5e36..c951c827 100644 --- a/src/ripple/ripple.js +++ b/src/ripple/ripple.js @@ -23,6 +23,7 @@ * Implements MDL component design pattern defined at: * https://github.com/jasonmayes/mdl-component-design-pattern * + * @constructor * @param {HTMLElement} element The element that will be upgraded. */ var MaterialRipple = function MaterialRipple(element) { @@ -36,7 +37,7 @@ /** * Store constants in one place so they can be updated easily. * - * @enum {String | Number} + * @enum {string | number} * @private */ MaterialRipple.prototype.Constant_ = { @@ -52,7 +53,7 @@ * JavaScript. This allows us to simply change it in one place should we * decide to modify at a later date. * - * @enum {String} + * @enum {string} * @private */ MaterialRipple.prototype.CssClasses_ = { @@ -164,23 +165,44 @@ this.element_.addEventListener('touchend', this.boundUpHandler); this.element_.addEventListener('blur', this.boundUpHandler); + /** + * Getter for frameCount_. + * @return {number} the frame count. + */ this.getFrameCount = function() { return this.frameCount_; }; + /** + * Setter for frameCount_. + * @param {number} fC the frame count. + */ this.setFrameCount = function(fC) { this.frameCount_ = fC; }; + /** + * Getter for rippleElement_. + * @return {Element} the ripple element. + */ this.getRippleElement = function() { return this.rippleElement_; }; + /** + * Sets the ripple X and Y coordinates. + * @param {number} newX the new X coordinate + * @param {number} newY the new Y coordinate + */ this.setRippleXY = function(newX, newY) { this.x_ = newX; this.y_ = newY; }; + /** + * Sets the ripple styles. + * @param {boolean} start whether or not this is the start frame. + */ this.setRippleStyles = function(start) { if (this.rippleElement_ !== null) { var transformString; @@ -214,6 +236,9 @@ } }; + /** + * Handles an animation frame. + */ this.animFrameHandler = function() { if (this.frameCount_-- > 0) { window.requestAnimationFrame(this.animFrameHandler.bind(this)); diff --git a/src/slider/slider.js b/src/slider/slider.js index 476b2d41..8aabe527 100644 --- a/src/slider/slider.js +++ b/src/slider/slider.js @@ -23,6 +23,7 @@ * Implements MDL component design pattern defined at: * https://github.com/jasonmayes/mdl-component-design-pattern * + * @constructor * @param {HTMLElement} element The element that will be upgraded. */ var MaterialSlider = function MaterialSlider(element) { @@ -37,7 +38,7 @@ /** * Store constants in one place so they can be updated easily. * - * @enum {String | Number} + * @enum {string | number} * @private */ MaterialSlider.prototype.Constant_ = { @@ -49,7 +50,7 @@ * JavaScript. This allows us to simply change it in one place should we * decide to modify at a later date. * - * @enum {String} + * @enum {string} * @private */ MaterialSlider.prototype.CssClasses_ = { @@ -123,10 +124,9 @@ /** * Handle updating of values. * - * @param {Event} event The event that fired. * @private */ - MaterialSlider.prototype.updateValueStyles_ = function(event) { + MaterialSlider.prototype.updateValueStyles_ = function() { // Calculate and apply percentages to div structure behind slider. var fraction = (this.element_.value - this.element_.min) / (this.element_.max - this.element_.min); @@ -169,7 +169,7 @@ /** * Update slider value. * - * @param {Number} value The value to which to set the control (optional). + * @param {number} value The value to which to set the control (optional). * @public */ MaterialSlider.prototype.change = function(value) { diff --git a/src/spinner/spinner.js b/src/spinner/spinner.js index 988aebfd..6fa74261 100644 --- a/src/spinner/spinner.js +++ b/src/spinner/spinner.js @@ -37,7 +37,7 @@ /** * Store constants in one place so they can be updated easily. * - * @enum {String | Number} + * @enum {string | number} * @private */ MaterialSpinner.prototype.Constant_ = { @@ -49,7 +49,7 @@ * JavaScript. This allows us to simply change it in one place should we * decide to modify at a later date. * - * @enum {String} + * @enum {string} * @private */ MaterialSpinner.prototype.CssClasses_ = { @@ -64,7 +64,7 @@ /** * Auxiliary method to create a spinner layer. * - * @param {Number} index Index of the layer to be created. + * @param {number} index Index of the layer to be created. * @public */ MaterialSpinner.prototype.createLayer = function(index) { diff --git a/src/switch/switch.js b/src/switch/switch.js index 3df47910..ce31c107 100644 --- a/src/switch/switch.js +++ b/src/switch/switch.js @@ -23,6 +23,7 @@ * Implements MDL component design pattern defined at: * https://github.com/jasonmayes/mdl-component-design-pattern * + * @constructor * @param {HTMLElement} element The element that will be upgraded. */ var MaterialSwitch = function MaterialSwitch(element) { @@ -36,7 +37,7 @@ /** * Store constants in one place so they can be updated easily. * - * @enum {String | Number} + * @enum {string | number} * @private */ MaterialSwitch.prototype.Constant_ = { @@ -48,7 +49,7 @@ * JavaScript. This allows us to simply change it in one place should we * decide to modify at a later date. * - * @enum {String} + * @enum {string} * @private */ MaterialSwitch.prototype.CssClasses_ = { @@ -121,12 +122,12 @@ * * @private */ - MaterialSwitch.prototype.blur_ = function(event) { + MaterialSwitch.prototype.blur_ = function() { // TODO: figure out why there's a focus event being fired after our blur, // so that we can avoid this hack. window.setTimeout(function() { this.inputElement_.blur(); - }.bind(this), this.Constant_.TINY_TIMEOUT); + }.bind(this), /** @type {number} */ (this.Constant_.TINY_TIMEOUT)); }; // Public methods. diff --git a/src/tabs/tabs.js b/src/tabs/tabs.js index cd375f70..4eb2d444 100644 --- a/src/tabs/tabs.js +++ b/src/tabs/tabs.js @@ -23,6 +23,7 @@ * Implements MDL component design pattern defined at: * https://github.com/jasonmayes/mdl-component-design-pattern * + * @constructor * @param {HTMLElement} element The element that will be upgraded. */ var MaterialTabs = function MaterialTabs(element) { @@ -37,7 +38,7 @@ /** * Store constants in one place so they can be updated easily. * - * @enum {String} + * @enum {string} * @private */ MaterialTabs.prototype.Constant_ = { @@ -49,7 +50,7 @@ * JavaScript. This allows us to simply change it in one place should we * decide to modify at a later date. * - * @enum {String} + * @enum {string} * @private */ MaterialTabs.prototype.CssClasses_ = { @@ -119,6 +120,13 @@ } }; + /** + * Constructor for an individual tab. + * + * @constructor + * @param {HTMLElement} tab The HTML element for the tab. + * @param {MaterialTabs} ctx The MaterialTabs object that owns the tab. + */ function MaterialTab(tab, ctx) { if (tab) { if (ctx.element_.classList.contains(ctx.CssClasses_.MDL_JS_RIPPLE_EFFECT)) { diff --git a/src/textfield/textfield.js b/src/textfield/textfield.js index 4b6c936e..9533df62 100644 --- a/src/textfield/textfield.js +++ b/src/textfield/textfield.js @@ -23,6 +23,7 @@ * Implements MDL component design pattern defined at: * https://github.com/jasonmayes/mdl-component-design-pattern * + * @constructor * @param {HTMLElement} element The element that will be upgraded. */ var MaterialTextfield = function MaterialTextfield(element) { @@ -36,7 +37,7 @@ /** * Store constants in one place so they can be updated easily. * - * @enum {String | Number} + * @enum {string | number} * @private */ MaterialTextfield.prototype.Constant_ = { @@ -49,7 +50,7 @@ * JavaScript. This allows us to simply change it in one place should we * decide to modify at a later date. * - * @enum {String} + * @enum {string} * @private */ MaterialTextfield.prototype.CssClasses_ = { @@ -172,7 +173,7 @@ /** * Update text field value. * - * @param {String} value The value to which to set the control (optional). + * @param {string} value The value to which to set the control (optional). * @public */ MaterialTextfield.prototype.change = function(value) { @@ -193,9 +194,10 @@ this.input_ = this.element_.querySelector('.' + this.CssClasses_.INPUT); if (this.input_) { - if (this.input_.hasAttribute(this.Constant_.MAX_ROWS_ATTRIBUTE)) { + if (this.input_.hasAttribute( + /** @type {string} */ (this.Constant_.MAX_ROWS_ATTRIBUTE))) { this.maxRows = parseInt(this.input_.getAttribute( - this.Constant_.MAX_ROWS_ATTRIBUTE), 10); + /** @type {string} */ (this.Constant_.MAX_ROWS_ATTRIBUTE)), 10); if (isNaN(this.maxRows)) { this.maxRows = this.Constant_.NO_MAX_ROWS; } diff --git a/src/third_party/rAF.js b/src/third_party/rAF.js index 8006703c..9af6924b 100644 --- a/src/third_party/rAF.js +++ b/src/third_party/rAF.js @@ -12,6 +12,10 @@ 'use strict'; if (!Date.now) { + /** + * Date.now polyfill. + * @return {Date} the current Date + */ Date.now = function() { return new Date().getTime(); }; } @@ -25,14 +29,17 @@ for (var i = 0; i < vendors.length && !window.requestAnimationFrame; ++i) { if (/iP(ad|hone|od).*OS 6/.test(window.navigator.userAgent) || !window.requestAnimationFrame || !window.cancelAnimationFrame) { var lastTime = 0; + /** + * requestAnimationFrame polyfill. + * @param {!Function} callback the callback function. + */ window.requestAnimationFrame = function(callback) { - var now = Date.now(); - var nextTime = Math.max(lastTime + 16, now); - return setTimeout(function() { callback(lastTime = nextTime); }, - nextTime - now); - }; + var now = Date.now(); + var nextTime = Math.max(lastTime + 16, now); + return setTimeout(function() { callback(lastTime = nextTime); }, + nextTime - now); + }; window.cancelAnimationFrame = clearTimeout; } })(); - diff --git a/src/tooltip/tooltip.js b/src/tooltip/tooltip.js index 924dc65b..b822e944 100644 --- a/src/tooltip/tooltip.js +++ b/src/tooltip/tooltip.js @@ -23,6 +23,7 @@ * Implements MDL component design pattern defined at: * https://github.com/jasonmayes/mdl-component-design-pattern * + * @constructor * @param {HTMLElement} element The element that will be upgraded. */ var MaterialTooltip = function MaterialTooltip(element) { @@ -36,7 +37,7 @@ /** * Store constants in one place so they can be updated easily. * - * @enum {String | Number} + * @enum {string | number} * @private */ MaterialTooltip.prototype.Constant_ = { @@ -48,7 +49,7 @@ * JavaScript. This allows us to simply change it in one place should we * decide to modify at a later date. * - * @enum {String} + * @enum {string} * @private */ MaterialTooltip.prototype.CssClasses_ = { diff --git a/utils/jscs-rules/closure-camel-case.js b/utils/jscs-rules/closure-camel-case.js new file mode 100644 index 00000000..4c1b5e35 --- /dev/null +++ b/utils/jscs-rules/closure-camel-case.js @@ -0,0 +1,68 @@ +/** + * @license + * Copyright 2015 Google Inc. All Rights Reserved. + * + * Licensed under the Apache License, Version 2.0 (the "License"); + * you may not use this file except in compliance with the License. + * You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ + +/** + * Checks that identifiers are written in camelCase (or UPPER_CASE), with the + * exception of optional parameters (opt_foo), which follow Closure convention. + */ + +'use strict'; + +module.exports = function() {}; + +/** + * Returns the option name to JSCS. + * @return {string} the option name. + */ +module.exports.prototype.getOptionName = function() { + return 'closureCamelCase'; +}; + +/** + * Configure the rule parameters. + * @param {boolean} value the value for this rule. + */ +module.exports.prototype.configure = function(value) { + // rule preparation and configuration + this._options = value; +}; + +/** + * Checks whether or not the rule is being broken. + * @param {Object} file the file being checked + * @param {Object} errors the current list of errors on the file + */ +module.exports.prototype.check = function(file, errors) { + if (!this._options) { + return; + } + file.iterateTokensByType('Identifier', function(token) { + var name = token.value; + if (name.replace(/^_+/g, '') + .replace(/^opt_+/g, '') + .replace(/_+$/g, '') + .indexOf('_') === -1 || + name.toUpperCase() === name) { + return; + } + errors.add( + 'All identifiers must be camelCase or UPPER_CASE', + token.loc.start.line, + token.loc.start.column + ); + }); +};