add docs for new sass functions

Author: mmalerba

src/material/core/theming/_m2-inspection.scss

@@ -5,8 +5,10 @@
 @use '../typography/typography-utils';
 @use '../typography/typography';
 
+/// Key used to access the Angular Material theme internals.
 $_internals: _mat-theming-internals-do-not-access;
 
+/// Keys that indicate a config object is a color config.
 $_color-keys: (
   primary,
   accent,
@@ -17,6 +19,7 @@ $_color-keys: (
   color, /* included for themes that incorrectly nest the color config: (color: (color: (....))) */
 );
 
+/// Keys that indicate a config object is a typography config.
 $_typography-keys: (
   headline-1,
   headline-2,
@@ -34,9 +37,23 @@ $_typography-keys: (
   overline,
 );
 
+/// The CSS typography properties supported by the inspection API.
 $_typography-properties: (font, font-family, line-height, font-size, letter-spacing, font-weight);
 
-/// Checks whether the given theme contains error objects.
+/// Gets the m2-config from the theme.
+@function _get-m2-config($theme) {
+  // It is possible for a user to pass a "density theme" that is just a number.
+  @if meta.type-of($theme) != 'map' {
+    @return $theme;
+  }
+  $internal: map.get($theme, $_internals, m2-config);
+  $theme: map.remove($theme, $_internals);
+  @return if(_is-error-theme($theme), $internal, $theme);
+}
+
+/// Checks whether the given theme contains error values.
+/// @param {*} $theme The theme to check.
+/// @return {Boolean} true if the theme contains error values, else false.
 @function _is-error-theme($theme) {
   @if meta.type-of($theme) != 'map' {
     @return false;
@@ -47,15 +64,24 @@ $_typography-properties: (font, font-family, line-height, font-size, letter-spac
   @return _is-error-theme(list.nth(map.values($theme), 1));
 }
 
-/// Gets the m2-config from the theme.
-@function _get-m2-config($theme) {
-  // It is possible for a user to pass a "density theme" that is just a number.
-  @if meta.type-of($theme) != 'map' {
-    @return $theme;
+/// Checks whether the given theme object has any of the given keys.
+/// @param {Map} $theme The theme to check
+/// @param {List} $keys The keys to check for
+/// @return {Boolean} Whether the theme has any of the given keys.
+@function _has-any-key($theme, $keys) {
+  @each $key in $keys {
+    @if map.has-key($theme, $key) {
+      @return true;
+    }
   }
-  $internal: map.get($theme, $_internals, m2-config);
-  $theme: map.remove($theme, $_internals);
-  @return if(_is-error-theme($theme), $internal, $theme);
+  @return false;
+}
+
+/// Checks whether the given theme is a density scale value.
+/// @param {*} $theme The theme to check.
+/// @return {Boolean} true if the theme is a density scale value, else false.
+@function _is-density-value($theme) {
+  @return $theme == minimum or $theme == maximum or meta.type-of($theme) == 'number';
 }
 
 /// Gets the type of theme represented by a theme object (light or dark).
@@ -177,16 +203,3 @@ $_typography-properties: (font, font-family, line-height, font-size, letter-spac
   }
   @error 'Valid systems are: base, color, typography, density. Got:' $system;
 }
-
-@function _has-any-key($theme, $keys) {
-  @each $key in $keys {
-    @if map.has-key($theme, $key) {
-      @return true;
-    }
-  }
-  @return false;
-}
-
-@function _is-density-value($theme) {
-  @return $theme == minimum or $theme == maximum or meta.type-of($theme) == 'number';
-}

src/material/core/theming/_theming.scss

@@ -601,6 +601,10 @@ $_internals: _mat-theming-internals-do-not-access;
   @return $density-scale;
 }
 
+/// Copies the given theme object and nests it within itself under a secret key and replaces the
+/// original map keys with error values. This allows the inspection API which is aware of the secret
+/// key to access the real values, but attempts to directly access the map will result in errors.
+/// @param {Map} $theme The theme map.
 @function _internalize-theme($theme) {
   @if map.has-key($theme, $_internals) {
     @return $theme;
@@ -619,6 +623,15 @@ $_internals: _mat-theming-internals-do-not-access;
   @return map.merge($error-theme, $internalized-theme);
 }
 
+/// Replaces concrete CSS values with errors in a theme object.
+/// Errors are represented as a map `(ERROR: <message>)`. Because maps are not valid CSS values,
+/// the Sass will not compile if the user tries to use any of the error theme values in their CSS.
+/// Users will see a message about `(ERROR: <message>)` not being a valid CSS value. Using the
+/// message, that winds up getting shown, we can help explain to users why they're getting the
+/// error.
+/// @param {*} $value The theme value to replace with errors.
+/// @param {String} $message The error message to sow users.
+/// @return {Map} A version of $value where concrete CSS values have been replaced with errors
 @function _replace-values-with-errors($value, $message) {
   $value-type: meta.type-of($value);
   @if $value-type == 'map' {