docs(material/theming): add SassDoc for public theming APIs

This adds "correct" SassDoc for the core theming APIs, including
parameters and return values with types.

It doesn't look like either WebStorm or VS Code actually _support_
SassDoc, but this at least makes our source a bit more documented.

Author: jelbourn

src/cdk/a11y/_index.scss

@@ -1,4 +1,6 @@
-@mixin a11y-visually-hidden {
+/// Emits a CSS class, `.cdk-visually-hidden`. This class can be applied to an element
+// to make that element visually hidden while remaining available to assitive technology.
+@mixin a11y-visually-hidden() {
   .cdk-visually-hidden {
     border: 0;
     clip: rect(0 0 0 0);
@@ -22,14 +24,14 @@
   }
 }
 
-// @deprecated Use `a11y-visually-hidden`.
-@mixin a11y {
+/// @deprecated Use `a11y-visually-hidden`.
+@mixin a11y() {
   @include a11y-visually-hidden;
 }
 
 /// Emits the mixin's content nested under `$selector-context` if `$selector-context`
 /// is non-empty.
-/// @param selector-context The selector under which to nest the mixin's content.
+/// @param {String} selector-context The selector under which to nest the mixin's content.
 @mixin _optionally-nest-content($selector-context) {
   @if ($selector-context == '') {
     @content;
@@ -45,9 +47,9 @@
 /// to Microsoft browsers. Chrome can be included by checking for the `html[hc]`
 /// attribute, however Chrome handles high contrast differently.
 ///
-/// @param target Which kind of high contrast setting to target. Defaults to `active`, can be
-///    `white-on-black` or `black-on-white`.
-/// @param encapsulation Whether to emit styles for view encapsulation. Values are:
+/// @param {String} target Type of high contrast setting to target. Defaults to `active`, can be
+///     `white-on-black` or `black-on-white`.
+/// @param {string} encapsulation Whether to emit styles for view encapsulation. Values are:
 ///     * `on` - works for `Emulated`, `Native`, and `ShadowDom`
 ///     * `off` - works for `None`
 ///     * `any` - works for all encapsulation modes by emitting the CSS twice (default).

src/cdk/overlay/_index.scss

@@ -12,7 +12,7 @@ $overlay-backdrop-color: rgba(0, 0, 0, 0.32) !default;
 $backdrop-animation-duration: 400ms !default;
 $backdrop-animation-timing-function: cubic-bezier(0.25, 0.8, 0.25, 1) !default;
 
-
+/// Emits structural styles required for cdk/overlay to function.
 @mixin overlay() {
   .cdk-overlay-container, .cdk-global-overlay-wrapper {
     // Disable events from being captured on the overlay container.

src/material/core/theming/_theming.scss

@@ -20,21 +20,23 @@ $_emitted-color: () !default;
 $_emitted-typography: () !default;
 $_emitted-density: () !default;
 
-// For a given hue in a palette, return the contrast color from the map of contrast palettes.
-// @param $palette
-// @param $hue
+/// For a given hue in a palette, return the contrast color from the map of contrast palettes.
+/// @param {Map} $palette The palette from which to extract a color.
+/// @param {String | Number} $hue The hue for which to get a contrast color.
+/// @returns {Color} The contrast color for the given palette and hue.
 @function get-contrast-color-from-palette($palette, $hue) {
   @return map.get(map.get($palette, contrast), $hue);
 }
 
 
-// Creates a map of hues to colors for a theme. This is used to define a theme palette in terms
-// of the Material Design hues.
-// @param $base-palette
-// @param $default
-// @param $lighter
-// @param $darker
-// @param $text
+/// Creates a map of hues to colors for a theme. This is used to define a theme palette in terms
+/// of the Material Design hues.
+/// @param {Map} $base-palette Map of hue keys to color values for the basis for this palette.
+/// @param {String | Number} $default The default hue for this palette.
+/// @param {String | Number} $lighter The "lighter" hue for this palette.
+/// @param {String | Number} $darker The "darker" hue for this palette.
+/// @param {String | Number} $text The "text" hue for this palette.
+/// @returns {Map} A complete Angular Material theming palette.
 @function define-palette($base-palette, $default: 500, $lighter: 100, $darker: 700,
   $text: $default) {
   $result: map.merge($base-palette, (
@@ -59,14 +61,15 @@ $_emitted-density: () !default;
 }
 
 
-// Gets a color from a theme palette (the output of mat-palette).
-// The hue can be one of the standard values (500, A400, etc.), one of the three preconfigured
-// hues (default, lighter, darker), or any of the aforementioned prefixed with "-contrast".
-//
-// @param $palette The theme palette (output of mat-palette).
-// @param $hue The hue from the palette to use. If this is a value between 0 and 1, it will
-//     be treated as opacity.
-// @param $opacity The alpha channel value for the color.
+/// Gets a color from a theme palette (the output of mat-palette).
+/// The hue can be one of the standard values (500, A400, etc.), one of the three preconfigured
+/// hues (default, lighter, darker), or any of the aforementioned prefixed with "-contrast".
+///
+/// @param {Map} $palette The palette from which to extract a color.
+/// @param {String | Number} $hue The hue from the palette to use. If this is a value between 0
+//     and 1, it will be treated as opacity.
+/// @param {Number} $opacity The alpha channel value for the color.
+/// @returns {Color} The color for the given palette, hue, and opacity.
 @function get-color-from-palette($palette, $hue: default, $opacity: null) {
   // If hueKey is a number between zero and one, then it actually contains an
   // opacity value, so recall this function with the default hue and that given opacity.
@@ -130,9 +133,12 @@ $_emitted-density: () !default;
   );
 }
 
-// Creates a container object for a light theme to be given to individual component theme mixins.
-// TODO: Remove legacy API and rename `$primary` to `$config`. Currently it cannot be renamed
+// TODO: Remove legacy API and rename `$primary` below to `$config`. Currently it cannot be renamed
 // as it would break existing apps that set the parameter by name.
+
+/// Creates a container object for a light theme to be given to individual component theme mixins.
+/// @param {Map} $primary The theme configuration object.
+/// @returns {Map} A complete Angular Material theme map.
 @function define-light-theme($primary, $accent: null, $warn: define-palette(palette.$red-palette)) {
   // This function creates a container object for the individual component theme mixins. Consumers
   // can construct such an object by calling this function, or by building the object manually.
@@ -167,9 +173,12 @@ $_emitted-density: () !default;
   @return private-create-backwards-compatibility-theme(_mat-validate-theme($result));
 }
 
-// Creates a container object for a dark theme to be given to individual component theme mixins.
-// TODO: Remove legacy API and rename `$primary` to `$config`. Currently it cannot be renamed
+// TODO: Remove legacy API and rename below `$primary` to `$config`. Currently it cannot be renamed
 // as it would break existing apps that set the parameter by name.
+
+/// Creates a container object for a dark theme to be given to individual component theme mixins.
+/// @param {Map} $primary The theme configuration object.
+/// @returns {Map} A complete Angular Material theme map.
 @function define-dark-theme($primary, $accent: null, $warn: define-palette(palette.$red-palette)) {
   // This function creates a container object for the individual component theme mixins. Consumers
   // can construct such an object by calling this function, or by building the object manually.
@@ -205,6 +214,10 @@ $_emitted-density: () !default;
 }
 
 /// Gets the color configuration from the given theme or configuration.
+/// @param {Map} $theme The theme map returned from `define-light-theme` or `define-dark-theme`.
+/// @param {Map} $default The default value returned if the given `$theme` does not include a
+///     `color` configuration.
+/// @returns {Map} Color configuration for a theme.
 @function get-color-config($theme, $default: null) {
   // If a configuration has been passed, return the config directly.
   @if not private-is-theme-object($theme) {
@@ -225,6 +238,11 @@ $_emitted-density: () !default;
 }
 
 /// Gets the density configuration from the given theme or configuration.
+/// @param {Map} $theme-or-config  The theme map returned from `define-light-theme` or
+//     `define-dark-theme`.
+/// @param {Map} $default The default value returned if the given `$theme` does not include a
+///     `density` configuration.
+/// @returns {Map} Density configuration for a theme.
 @function get-density-config($theme-or-config, $default: 0) {
   // If a configuration has been passed, return the config directly.
   @if not private-is-theme-object($theme-or-config) {
@@ -240,6 +258,11 @@ $_emitted-density: () !default;
 
 /// Gets the typography configuration from the given theme or configuration.
 /// For backwards compatibility, typography is not included by default.
+/// @param {Map} $theme-or-config  The theme map returned from `define-light-theme` or
+//     `define-dark-theme`.
+/// @param {Map} $default The default value returned if the given `$theme` does not include a
+///     `typography` configuration.
+/// @returns {Map} Typography configuration for a theme.
 @function get-typography-config($theme-or-config, $default: null) {
   // If a configuration has been passed, return the config directly.
   @if not private-is-theme-object($theme-or-config) {

src/material/core/typography/_typography-utils.scss

@@ -1,32 +1,44 @@
 @use 'sass:map';
 @use 'sass:meta';
 @use 'sass:string';
+
+
 // Utility for fetching a nested value from a typography config.
 @function _mat-get-type-value($config, $level, $name) {
   @return map.get(map.get($config, $level), $name);
 }
 
-// Gets the font size for a level inside a typography config.
+/// Gets the font size for a level inside a typography config.
+/// @param {Map} $config A typography config.
+/// @param {Map} $level A typography level.
 @function font-size($config, $level) {
   @return _mat-get-type-value($config, $level, font-size);
 }
 
-// Gets the line height for a level inside a typography config.
+/// Gets the line height for a level inside a typography config.
+/// @param {Map} $config A typography config.
+/// @param {Map} $level A typography level.
 @function line-height($config, $level) {
   @return _mat-get-type-value($config, $level, line-height);
 }
 
-// Gets the font weight for a level inside a typography config.
+/// Gets the font weight for a level inside a typography config.
+/// @param {Map} $config A typography config.
+/// @param {Map} $level A typography level.
 @function font-weight($config, $level) {
   @return _mat-get-type-value($config, $level, font-weight);
 }
 
-// Gets the letter spacing for a level inside a typography config.
+/// Gets the letter spacing for a level inside a typography config.
+/// @param {Map} $config A typography config.
+/// @param {Map} $level A typography level.
 @function letter-spacing($config, $level) {
   @return _mat-get-type-value($config, $level, letter-spacing);
 }
 
-// Gets the font-family from a typography config and removes the quotes around it.
+/// Gets the font-family from a typography config and removes the quotes around it.
+/// @param {Map} $config A typography config.
+/// @param {Map} $level A typography level.
 @function font-family($config, $level: null) {
   $font-family: map.get($config, font-family);
 
@@ -38,8 +50,13 @@
   @return if(meta.type-of($font-family) == string, string.unquote($font-family), $font-family);
 }
 
-// Outputs the shorthand `font` CSS property, based on a set of typography values. Falls back to
-// the individual properties if a value that isn't allowed in the shorthand is passed in.
+/// Outputs the shorthand `font` CSS property, based on a set of typography values. Falls back to
+/// the individual properties if a value that isn't allowed in the shorthand is passed in.
+/// @param {String} $font-size The font-size value.
+/// @param {String | Number} $font-weight The font-weight value.
+/// @param {String | Number} $line-height The line-height value.
+/// @param {String} $font-family The font-family value.
+/// @returns {String} The `font` shorthand value combining the given parts.
 @mixin font-shorthand($font-size, $font-weight, $line-height, $font-family) {
   // If any of the values are set to `inherit`, we can't use the shorthand
   // so we fall back to passing in the individual properties.
@@ -65,7 +82,9 @@
   }
 }
 
-// Converts a typography level into CSS styles.
+/// Emits CSS styles for the given typography level.
+/// @param {Map} $config A typography config.
+/// @param {Map} $level A typography level.
 @mixin typography-level($config, $level) {
   $font-size: font-size($config, $level);
   $font-weight: font-weight($config, $level);

src/material/core/typography/_typography.scss

@@ -2,7 +2,13 @@
 @use 'typography-utils';
 @use '../theming/theming';
 
-// Represents a typography level from the Material design spec.
+/// Defines a typography level from the Material Design spec.
+/// @param {String} $font-size The font-size for this level.
+/// @param {String | Number} $line-height The line-height for this level.
+/// @param {String | Number} $font-weight The font-weight for this level.
+/// @param {String} $font-family The font-family for this level.
+/// @param {String} $letter-spacing The letter-spacing for this level.
+/// @returns {Map} A map representing the definition of this typpographic level.
 @function define-typography-level(
   $font-size,
   $line-height: $font-size,
@@ -19,10 +25,27 @@
   );
 }
 
-// Represents a collection of typography levels.
-// Defaults come from https://material.io/guidelines/style/typography.html
-// Note: The spec doesn't mention letter spacing. The values here come from
-// eyeballing it until it looked exactly like the spec examples.
+/// Defines a collection of typography levels to configure typography for an application.
+/// Any level not specified defaults to the values defined in the Material Design specification:
+/// https://material.io/guidelines/style/typography.html.
+///
+/// Note that the Material Design specification does not describe explicit letter-spacing values.
+/// The values here come from reverse engineering the Material Design examples.
+/// @param {String} $font-family Default font-family for levels that don't specify font-family.
+/// @param {Map} $display-4 Configuration for the "display-4" typographic level.
+/// @param {Map} $display-3 Configuration for the "display-3" typographic level.
+/// @param {Map} $display-2 Configuration for the "display-2" typographic level.
+/// @param {Map} $display-1 Configuration for the "display-1" typographic level.
+/// @param {Map} $headline Configuration for the "headline" typographic level.
+/// @param {Map} $title Configuration for the "title" typographic level.
+/// @param {Map} $subheading-2 Configuration for the "subheading-2" typographic level.
+/// @param {Map} $subheading-1 Configuration for the "subheading-1" typographic level.
+/// @param {Map} $body-2 Configuration for the "body-2" typographic level.
+/// @param {Map} $body-1 Configuration for the "body-1" typographic level.
+/// @param {Map} $caption Configuration for the "caption" typographic level.
+/// @param {Map} $button Configuration for the "button" typographic level.
+/// @param {Map} $input Configuration for the "input" typographic level.
+/// @returns {Map} A typography config for the application.
 @function define-typography-config(
   $font-family:   'Roboto, "Helvetica Neue", sans-serif',
   $display-4:     define-typography-level(112px, 112px, 300, $letter-spacing: -0.05em),
@@ -148,8 +171,12 @@
   @return $config;
 }
 
-// Adds the base typography styles, based on a config.
-// stylelint-disable-next-line material/theme-mixin-api
+// stylelint-disable material/theme-mixin-api
+
+/// Emits baseline typographic styles based on a given config.
+/// @param {Map} $config-or-theme A typography config for an entire theme.
+/// @param {String} $selector Ancestor selector under which native elements, such as h1, will
+///     be styled.
 @mixin typography-hierarchy($config-or-theme, $selector: '.mat-typography') {
   $config: private-typography-to-2014-config(theming.get-typography-config($config-or-theme));
 
@@ -236,3 +263,5 @@
     margin: 0 0 64px;
   }
 }
+
+// stylelint-enable material/theme-mixin-api