Improve documentation

2 files changed, 18 insertions, 13 deletions

diff --git a/docs/src/reference/scripting.md b/docs/src/reference/scripting.md
index 7d40f256..d125bf5b 100644
--- a/docs/src/reference/scripting.md
+++ b/docs/src/reference/scripting.md
@@ -81,7 +81,8 @@ It explains #name.
 Sum is #add(2, 3).
 ```
 
-Let bindings can be used to destructure arrays and dictionaries.
+Let bindings can also be used to destructure [arrays]($type/array) and
+[dictionaries]($type/dictionary).
 
 ```example
 #let (x, y) = (1, 2)
@@ -92,10 +93,11 @@ The first element is #a.
 The last element is #b.
 
 #let books = (
-  "Shakespeare": "Hamlet",
-  "Homer": "The Odyssey",
-  "Austen": "Persuasion",
+  Shakespeare: "Hamlet",
+  Homer: "The Odyssey",
+  Austen: "Persuasion",
 )
+
 #let (Austen,) = books
 Austen wrote #Austen.
 
@@ -104,14 +106,13 @@ Homer wrote #h.
 
 #let (Homer, ..other) = books
 #for (author, title) in other [
-  #author wrote #title, 
+  #author wrote #title.
 ]
 ```
 
-Note that the underscore `_` is the only identifier that can
-be used multiple times in the same assignment.
+You can use the underscore to discard elements in a destructuring pattern:
 
-```
+```example
 #let (_, y, _) = (1, 2, 3)
 The y coordinate is #y.
 ```
diff --git a/docs/src/reference/types.md b/docs/src/reference/types.md
index 816cc391..184da137 100644
--- a/docs/src/reference/types.md
+++ b/docs/src/reference/types.md
@@ -526,11 +526,6 @@ Fails with an error if the index is out of bounds.
   The index at which to retrieve the item.
 - returns: any
 
-### enumerate()
-Returns an array of the values along with their indices.
-
-- returns: array
-
 ### push()
 Add a value to the end of the array.
 
@@ -616,6 +611,15 @@ transformed with the given function.
   The function to apply to each item.
 - returns: array
 
+### enumerate()
+Returns a new array with the values alongside their indices.
+
+The returned array consists of `(index, value)` pairs in the form of length-2
+arrays. These can be [destructured]($scripting/#bindings) with a let binding or
+for loop.
+
+- returns: array
+
 ### fold()
 Folds all items into a single value using an accumulator function.