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

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 Default hue for this palette.
+/// @param {String | Number} $lighter "lighter" hue for this palette.
+/// @param {String | Number} $darker "darker" hue for this palette.
+/// @param {String | Number} $text "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