Add documentation for map functions

source/code-snippets/_example-map-get.html.erb

@@ -0,0 +1,11 @@
+<% example(autogen_css: false) do %>
+$font-weights: ("regular": 400, "medium": 500, "bold": 700);
+
+@debug map-get($font-weights, "medium"); // 500
+@debug map-get($font-weights, "extra-bold"); // null
+===
+$font-weights: ("regular": 400, "medium": 500, "bold": 700)
+
+@debug map-get($font-weights, "medium")  // 500
+@debug map-get($font-weights, "extra-bold")  // null
+<% end %>

source/code-snippets/_example-mixin-arbitrary-keyword-arguments.html.erb

@@ -0,0 +1,41 @@
+<% example do %>
+@mixin syntax-colors($args...) {
+  @debug keywords($args); // (string: #080, comment: #800, $variable: $60b)
+
+  @each $name, $color in keywords($args) {
+    pre span.stx-#{$name} {
+      color: $color;
+    }
+  }
+}
+
+@include syntax-colors(
+  $string: #080,
+  $comment: #800,
+  $variable: #60b,
+)
+===
+@mixin syntax-colors($args...)
+  @debug keywords($args)  // (string: #080, comment: #800, $variable: $60b)
+
+  @each $name, $color in keywords($args)
+    pre span.stx-#{$name}
+      color: $color
+
+
+
+
+@include syntax-colors($string: #080, $comment: #800, $variable: #60b);
+===
+pre span.stx-string {
+  color: #080;
+}
+
+pre span.stx-comment {
+  color: #800;
+}
+
+pre span.stx-variable {
+  color: #60b;
+}
+<% end %>

source/documentation/at-rules/function.html.md.erb

@@ -161,7 +161,7 @@ arguments to that function are passed to that argument as a [list][]. This
 argument is known as an [argument list][].
 
 [list]: ../values/lists
-[variable argument list]: ../values/lists#argument-lists
+[argument list]: ../values/lists#argument-lists
 
 <% example do %>
 @function min($numbers...) {

source/documentation/at-rules/mixin.html.md.erb

@@ -224,7 +224,7 @@ arguments to that mixin are passed to that argument as a [list][]. This argument
 is known as an [argument list][].
 
 [list]: ../values/lists
-[variable argument list]: ../values/lists#argument-lists
+[argument list]: ../values/lists#argument-lists
 
 <% example do %>
 @mixin order($height, $selectors...) {
@@ -264,43 +264,7 @@ that were passed to the mixin as a [map][] from argument names (not including
 
 <%# TODO(nweiz): auto-generate this CSS once we're compiling with Dart Sass %>
 
-<% example do %>
-@mixin syntax-colors($args...) {
-  @each $name, $color in keywords($args) {
-    pre span.stx-#{$name} {
-      color: $color;
-    }
-  }
-}
-
-@include syntax-colors(
-  $string: #080,
-  $comment: #800,
-  $variable: #60b,
-)
-===
-@mixin syntax-colors($args...)
-  @each $name, $color in keywords($args)
-    pre span.stx-#{$name}
-      color: $color
-
-
-
-
-@include syntax-colors($string: #080, $comment: #800, $variable: #60b);
-===
-pre span.stx-string {
-  color: #080;
-}
-
-pre span.stx-comment {
-  color: #800;
-}
-
-pre span.stx-variable {
-  color: #60b;
-}
-<% end %>
+<%= partial 'code-snippets/example-mixin-arbitrary-keyword-arguments' %>
 
 <% fun_fact do %>
 If you don't ever pass an argument list to the [`keywords()` function][], that

source/documentation/functions/maps.html.md.erb

@@ -0,0 +1,152 @@
+---
+title: Map Functions
+---
+
+
+<% function 'keywords($args)', returns: 'map' do %>
+Returns the keywords passed to a mixin or function that takes [arbitrary
+arguments][]. The `$args` argument must be an [argument list][].
+
+[arbitrary arguments]: ../at-rules/mixin#taking-arbitrary-arguments
+[argument list]: ../values/lists#argument-lists
+
+The keywords are returned as a map from argument names as unquoted strings (not
+including `$`) to the values of those arguments.
+
+<%= partial 'code-snippets/example-mixin-arbitrary-keyword-arguments' %>
+<% end %>
+
+
+<% function 'map-get($map, $key)' do %>
+
+Returns the value in `$map` associated with `$key`.
+
+If `$map` doesn't have a value associated with `$key`, returns [`null`][].
+
+[`null`]: ../values/null
+
+<%= partial 'code-snippets/example-map-get' %>
+<% end %>
+
+
+<% function 'map-has-key($map, $key)', returns: 'boolean' do %>
+Returns whether `$map` contains a value associated with `$key`.
+
+<% example(autogen_css: false) do %>
+$font-weights: ("regular": 400, "medium": 500, "bold": 700);
+
+@debug map-has-key($font-weights, "regular"); // true
+@debug map-has-key($font-weights, "bolder"); // false
+===
+$font-weights: ("regular": 400, "medium": 500, "bold": 700)
+
+@debug map-has-key($font-weights, "regular")  // true
+@debug map-has-key($font-weights, "bolder")  // false
+<% end %>
+<% end %>
+
+
+<% function 'map-keys($map)', returns: 'list' do %>
+Returns a comma-separated list of all the keys in `$map`.
+
+<% example(autogen_css: false) do %>
+$font-weights: ("regular": 400, "medium": 500, "bold": 700);
+
+@debug map-keys($font-weights); // "regular", "medium", "bold"
+===
+$font-weights: ("regular": 400, "medium": 500, "bold": 700)
+
+@debug map-keys($font-weights)  // "regular", "medium", "bold"
+<% end %>
+<% end %>
+
+
+<% function 'map-merge($map1, $map2)', returns: 'map' do %>
+Returns a new map with all the keys and values from both `$map1` and `$map2`.
+
+This can also be used to add a new value or overrwrite a value in `$map1`, by
+passing a single key/value pair as `$map2`.
+
+If both `$map1` and `$map2` have the same key, `$map2`'s value takes precedence.
+
+All keys in the returned map that also appear in `$map1` have the same order as
+in `$map1`. New keys from `$map2` appear at the end of the map.
+
+<% example(autogen_css: false) do %>
+$light-weights: ("lightest": 100, "light": 300);
+$heavy-weights: ("medium": 500, "bold": 700);
+
+@debug map-merge($light-weights, $heavy-weights);
+// (
+//   "lightest": 100,
+//   "light": 300,
+//   "medium": 500,
+//   "bold": 700
+// )
+
+// map-merge() can be used to add a single key/value pair to a map.
+@debug map-merge($light-weights, ("lighter": 200));
+// ("lightest": 100, "light": 300, "lighter": 200)
+
+// It can also be used to overwrite a value in a map.
+@debug map-merge($light-weights, ("light": 200));
+// ("lightest": 100, "light": 200)
+===
+$light-weights: ("lightest": 100, "light": 300)
+$heavy-weights: ("medium": 500, "bold": 700)
+
+@debug map-merge($light-weights, $heavy-weights)
+// (
+//   "lightest": 100,
+//   "light": 300,
+//   "medium": 500,
+//   "bold": 700
+// )
+
+// map-merge() can be used to add a single key/value pair to a map.
+@debug map-merge($light-weights, ("lighter": 200))
+// ("lightest": 100, "light": 300, "lighter": 200)
+
+// It can also be used to overwrite a value in a map.
+@debug map-merge($light-weights, ("light": 200))
+// ("lightest": 100, "light": 200)
+<% end %>
+<% end %>
+
+
+<% function 'map-remove($map, $keys...)', returns: 'map' do %>
+Returns a copy of `$map` without any values associated with `$keys`.
+
+If a key in `$keys` doesn't have an associated value in `$map`, it's ignored.
+
+<% example(autogen_css: false) do %>
+$font-weights: ("regular": 400, "medium": 500, "bold": 700);
+
+@debug map-remove($font-weights, "regular"); // ("medium": 500, "bold": 700)
+@debug map-remove($font-weights, "regular", "bold"); // ("medium": 500)
+@debug map-remove($font-weights, "bolder");
+// ("regular": 400, "medium": 500, "bold": 700)
+===
+$font-weights: ("regular": 400, "medium": 500, "bold": 700)
+
+@debug map-remove($font-weights, "regular")  // ("medium": 500, "bold": 700)
+@debug map-remove($font-weights, "regular", "bold")  // ("medium": 500)
+@debug map-remove($font-weights, "bolder")
+// ("regular": 400, "medium": 500, "bold": 700)
+<% end %>
+<% end %>
+
+
+<% function 'map-values($map)', returns: 'list' do %>
+Returns a comma-separated list of all the values in `$map`.
+
+<% example(autogen_css: false) do %>
+$font-weights: ("regular": 400, "medium": 500, "bold": 700);
+
+@debug map-values($font-weights); // 400, 500, 700
+===
+$font-weights: ("regular": 400, "medium": 500, "bold": 700)
+
+@debug map-values($font-weights)  // 400, 500, 700
+<% end %>
+<% end %>

source/documentation/values/lists.html.md.erb

@@ -68,7 +68,7 @@ in a list, and assigns that element to a variable.
 
 <%= partial 'code-snippets/example-each-list' %>
 
-### Adding to a List
+### Add to a List
 
 It's also useful to add elements to a list. The [`append($list, $val)`
 function][] takes a list and a value, and returns a copy of the list with the value
@@ -86,7 +86,7 @@ modify the original list.
 @debug append([col1-line1], col1-line2)  // [col1-line1, col1-line2]
 <% end %>
 
-### Finding Elements in a List
+### Find an Element in a List
 
 If you need to check if an element is in a list or figure out what index it's
 at, use the [`index($list, $value)` function][]. This takes a list and a value
@@ -162,3 +162,16 @@ $prefixes-by-browser: ("firefox": moz, "safari": webkit, "ie": ms)
 
 @debug prefixes-for-browsers("firefox" "ie")  // moz ms
 <% end %>
+
+## Argument Lists
+
+When you declare a mixin or function that takes [arbitrary arguments][], the
+value you get is a special list known as an *argument list*. It acts just like a
+list that contains all the arguments passed to the mixin or function, with one
+extra feature: if the user passed keyword arguments, they can be accessed as a
+map by passing the argument list to the [`keywords()` function][].
+
+<%= partial 'code-snippets/example-mixin-arbitrary-keyword-arguments' %>
+
+[arbitrary arguments]: ../at-rules/mixin#taking-arbitrary-arguments
+[`keywords()` function]: ../functions/maps#keywords

source/documentation/values/maps.html.md.erb

@@ -53,17 +53,7 @@ returns [`null`][] if the map doesn't contain the key.
 the [`map-get($map, $key)` function]: ../functions/maps#map-get
 [`null`]: null
 
-<% example(autogen_css: false) do %>
-$font-weights: ("regular": 400, "medium": 500, "bold": 700);
-
-@debug map-get($font-weights, "medium"); // 500
-@debug map-get($font-weights, "extra-bold"); // null
-===
-$font-weights: ("regular": 400, "medium": 500, "bold": 700)
-
-@debug map-get($font-weights, "medium")  // 500
-@debug map-get($font-weights, "extra-bold")  // null
-<% end %>
+<%= partial 'code-snippets/example-map-get' %>
 
 ### Do Something for Every Pair
 
@@ -76,7 +66,7 @@ The [`@each` rule]: ../at-rules/control/each
 
 <%= partial 'code-snippets/example-each-map' %>
 
-### Adding to a Map
+### Add to a Map
 
 It's also useful to add new pairs to a map, or to replace the value for an
 existing key. The [`map-merge($map1, $map2)` function][] does this: it returns a
@@ -93,7 +83,7 @@ $heavy-weights: ("medium": 500, "bold": 700);
 //   "lightest": 100,
 //   "light": 300,
 //   "medium": 500,
-//   "bold": 700,
+//   "bold": 700
 // )
 ===
 $light-weights: ("lightest": 100, "light": 300)
@@ -104,7 +94,7 @@ $heavy-weights: ("medium": 500, "bold": 700)
 //   "lightest": 100,
 //   "light": 300,
 //   "medium": 500,
-//   "bold": 700,
+//   "bold": 700
 // )
 <% end %>