refactor(colors): clean up Closure / JSDoc comments and types

Relates to #11673

Author: Splaktar

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
    *  <hljs lang="js">
@@ -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
      * <hljs lang="js">
@@ -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,16 +159,22 @@
 
     /**
      * 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]]);
     }
 
     /**
      * 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,27 +208,38 @@
         // 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;
       }
 
       return palette;
     }
 
+    /**
+     * @param {Array} parts
+     * @param {string} theme name
+     * @return {*}
+     */
     function extractHue(parts, theme) {
       var themeColors = $mdTheming.THEMES[theme].colors;
 
       if (parts[1] === 'hue') {
         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 @@
    *   </div>
    * </hljs>
    *
-   * `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.
+   *
    * <hljs lang="html">
    *   <md-card md-colors="::{background: '{{theme}}-primary-700'}">
    *   </md-card>
    * </hljs>
-   *
    */
   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
              * <hljs lang="html">
              *   <div md-theme="myTheme">
              *     <div md-colors="{background: 'primary-600'}">
@@ -310,8 +334,8 @@
              *   </div>
              * </hljs>
              *
-             * '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 @@
         }
       }
     };
-
   }
-
-
 })();

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) {