diff --git a/src/components/colors/colors.js b/src/components/colors/colors.js index 1f7d41f527a..cb53b58f0cd 100644 --- a/src/components/colors/colors.js +++ b/src/components/colors/colors.js @@ -26,9 +26,10 @@ * @module material.components.colors * * @description - * With only defining themes, one couldn't get non AngularJS Material elements colored with Material colors, - * `$mdColors` service is used by the md-color directive to convert the 1..n color expressions to RGBA values and will apply - * those values to element as CSS property values. + * With only defining themes, one couldn't get non AngularJS Material elements colored with + * Material colors, `$mdColors` service is used by the md-color directive to convert the + * 1..n color expressions to RGBA values and will apply those values to element as CSS property + * values. * * @usage * @@ -61,9 +62,9 @@ * Gets a color json object, keys are css properties and values are string of the wanted color * Then calculate the rgba() values based on the theme color parts * - * @param {DOMElement} element the element to apply the styles on. - * @param {object} colorExpression json object, keys are css properties and values are string of the wanted color, - * for example: `{color: 'red-A200-0.3'}`. + * @param {angular.element} element the element to apply the styles on. + * @param {Object} colorExpression json object, keys are css properties and values are string of + * the wanted color, for example: `{color: 'red-A200-0.3'}`. * * @usage * @@ -86,7 +87,6 @@ } catch (e) { $log.error(e.message); } - } /** @@ -116,9 +116,10 @@ /** * Return the parsed color - * @param color hashmap of color definitions - * @param contrast whether use contrast color for foreground - * @returns rgba color string + * @param {{hue: *, theme: any, palette: *, opacity: (*|string|number)}} color hash map of color + * definitions + * @param {boolean=} contrast whether use contrast color for foreground. Defaults to false. + * @returns {string} rgba color string */ function parseColor(color, contrast) { contrast = contrast || false; @@ -134,10 +135,9 @@ /** * Convert the color expression into an object with scope-interpolated values * Then calculate the rgba() values based on the theme color parts - * - * @results Hashmap of CSS properties with associated `rgba( )` string vales - * - * + * @param {Object} themeColors json object, keys are css properties and values are string of + * the wanted color, for example: `{color: 'red-A200-0.3'}`. + * @return {Object} Hashmap of CSS properties with associated `rgba()` string values */ function interpolateColors(themeColors) { var rgbColors = {}; @@ -159,9 +159,12 @@ /** * Check if expression has defined theme - * e.g. - * 'myTheme-primary' => true - * 'red-800' => false + * For instance: + * 'myTheme-primary' => true + * 'red-800' => false + * @param {string} expression color expression like 'red-800', 'red-A200-0.3', + * 'myTheme-primary', or 'myTheme-primary-400' + * @return {boolean} true if the expression has a theme part, false otherwise. */ function hasTheme(expression) { return angular.isDefined($mdTheming.THEMES[expression.split('-')[0]]); @@ -169,6 +172,9 @@ /** * For the evaluated expression, extract the color parts into a hash map + * @param {string} expression color expression like 'red-800', 'red-A200-0.3', + * 'myTheme-primary', or 'myTheme-primary-400' + * @returns {{hue: *, theme: any, palette: *, opacity: (*|string|number)}} */ function extractColorOptions(expression) { var parts = expression.split('-'); @@ -185,6 +191,9 @@ /** * Calculate the theme palette name + * @param {Array} parts + * @param {string} theme name + * @return {string} */ function extractPalette(parts, theme) { // If the next section is one of the palettes we assume it's a two word palette @@ -199,7 +208,9 @@ // If the palette is not in the palette list it's one of primary/accent/warn/background var scheme = $mdTheming.THEMES[theme].colors[palette]; if (!scheme) { - throw new Error($mdUtil.supplant('mdColors: couldn\'t find \'{palette}\' in the palettes.', {palette: palette})); + throw new Error($mdUtil.supplant( + 'mdColors: couldn\'t find \'{palette}\' in the palettes.', + {palette: palette})); } palette = scheme.name; } @@ -207,6 +218,11 @@ return palette; } + /** + * @param {Array} parts + * @param {string} theme name + * @return {*} + */ function extractHue(parts, theme) { var themeColors = $mdTheming.THEMES[theme].colors; @@ -214,12 +230,16 @@ var hueNumber = parseInt(parts.splice(2, 1)[0], 10); if (hueNumber < 1 || hueNumber > 3) { - throw new Error($mdUtil.supplant('mdColors: \'hue-{hueNumber}\' is not a valid hue, can be only \'hue-1\', \'hue-2\' and \'hue-3\'', {hueNumber: hueNumber})); + throw new Error($mdUtil.supplant( + 'mdColors: \'hue-{hueNumber}\' is not a valid hue, can be only \'hue-1\', \'hue-2\' and \'hue-3\'', + {hueNumber: hueNumber})); } parts[1] = 'hue-' + hueNumber; if (!(parts[0] in themeColors)) { - throw new Error($mdUtil.supplant('mdColors: \'hue-x\' can only be used with [{availableThemes}], but was used with \'{usedTheme}\'', { + throw new Error($mdUtil.supplant( + 'mdColors: \'hue-x\' can only be used with [{availableThemes}], but was used with \'{usedTheme}\'', + { availableThemes: Object.keys(themeColors).join(', '), usedTheme: parts[0] })); @@ -261,14 +281,14 @@ * * * - * `mdColors` directive will automatically watch for changes in the expression if it recognizes an interpolation - * expression or a function. For performance options, you can use `::` prefix to the `md-colors` expression - * to indicate a one-time data binding. + * `mdColors` directive will automatically watch for changes in the expression if it recognizes + * an interpolation expression or a function. For performance options, you can use `::` prefix to + * the `md-colors` expression to indicate a one-time data binding. + * * * * * - * */ function MdColorsDirective($mdColors, $mdUtil, $log, $parse) { return { @@ -282,6 +302,10 @@ var lastColors = {}; + /** + * @param {string=} theme + * @return {Object} colors found in the specified theme + */ var parseColors = function (theme) { if (typeof theme !== 'string') { theme = ''; @@ -298,10 +322,10 @@ var colors = $parse(attrs.mdColors)(scope); /** - * If mdTheme is defined up the DOM tree - * we add mdTheme theme to colors who doesn't specified a theme + * If mdTheme is defined higher up the DOM tree, + * we add mdTheme's theme to the colors which don't specify a theme. * - * # example + * @example * *
*
@@ -310,8 +334,8 @@ *
* * - * 'primary-600' will be 'myTheme-primary-600', - * but 'mySecondTheme-accent-200' will stay the same cause it has a theme prefix + * 'primary-600' will be changed to 'myTheme-primary-600', + * but 'mySecondTheme-accent-200' will not be changed since it has a theme defined. */ if (mdThemeController) { Object.keys(colors).forEach(function (prop) { @@ -327,6 +351,9 @@ return colors; }; + /** + * @param {Object} colors + */ var cleanElement = function (colors) { if (!angular.equals(colors, lastColors)) { var keys = Object.keys(lastColors); @@ -344,7 +371,8 @@ }; /** - * Registering for mgTheme changes and asking mdTheme controller run our callback whenever a theme changes + * Registering for mgTheme changes and asking mdTheme controller run our callback whenever + * a theme changes. */ var unregisterChanges = angular.noop; @@ -375,6 +403,9 @@ }; + /** + * @return {boolean} + */ function shouldColorsWatch() { // Simulate 1x binding and mark mdColorsWatch == false var rawColorExpression = tAttrs.mdColors; @@ -391,8 +422,5 @@ } } }; - } - - })(); diff --git a/src/core/util/color.js b/src/core/util/color.js index 2e9135d6c71..7a87a307656 100644 --- a/src/core/util/color.js +++ b/src/core/util/color.js @@ -30,7 +30,7 @@ function ColorUtilFactory() { /** * Converts rgba value to hex string - * @param color {string} + * @param {string} color * @returns {string} */ function rgbaToHex(color) { @@ -46,7 +46,7 @@ function ColorUtilFactory() { /** * Converts an RGB color to RGBA - * @param color {string} + * @param {string} color * @returns {string} */ function rgbToRgba (color) { @@ -55,7 +55,7 @@ function ColorUtilFactory() { /** * Converts an RGBA color to RGB - * @param color {string} + * @param {string} color * @returns {string} */ function rgbaToRgb (color) {