Better reduce docs (#4493)

Based on conversation with Josh and Jordan earlier this week.

docs/kcl/std.json

@@ -158454,9 +158454,9 @@
     "unpublished": false,
     "deprecated": false,
     "examples": [
-      "fn decagon = (radius) => {\n  step = 1 / 10 * tau()\n  sketch001 = startSketchAt([cos(0) * radius, sin(0) * radius])\n  return reduce([1..10], sketch001, (i, sg) => {\n  x = cos(step * i) * radius\n  y = sin(step * i) * radius\n  return lineTo([x, y], sg)\n})\n}\ndecagon(5.0)\n  |> close(%)",
-      "array = [1, 2, 3]\nsum = reduce(array, 0, (i, result_so_far) => {\n  return i + result_so_far\n})\nassertEqual(sum, 6, 0.00001, \"1 + 2 + 3 summed is 6\")",
-      "fn add = (a, b) => {\n  return a + b\n}\nfn sum = (array) => {\n  return reduce(array, 0, add)\n}\nassertEqual(sum([1, 2, 3]), 6, 0.00001, \"1 + 2 + 3 summed is 6\")"
+      "// This function adds two numbers.\nfn add = (a, b) => {\n  return a + b\n}\n\n// This function adds an array of numbers.\n// It uses the `reduce` function, to call the `add` function on every\n// element of the `array` parameter. The starting value is 0.\nfn sum = (array) => {\n  return reduce(array, 0, add)\n}\n\n/* The above is basically like this pseudo-code:\nfn sum(array):\n    let sumSoFar = 0\n    for i in array:\n        sumSoFar = add(sumSoFar, i)\n    return sumSoFar */\n\n\n// We use `assertEqual` to check that our `sum` function gives the\n// expected result. It's good to check your work!\nassertEqual(sum([1, 2, 3]), 6, 0.00001, \"1 + 2 + 3 summed is 6\")",
+      "// This example works just like the previous example above, but it uses\n// an anonymous `add` function as its parameter, instead of declaring a\n// named function outside.\narray = [1, 2, 3]\nsum = reduce(array, 0, (i, result_so_far) => {\n  return i + result_so_far\n})\n\n// We use `assertEqual` to check that our `sum` function gives the\n// expected result. It's good to check your work!\nassertEqual(sum, 6, 0.00001, \"1 + 2 + 3 summed is 6\")",
+      "// Declare a function that sketches a decagon.\nfn decagon = (radius) => {\n  // Each side of the decagon is turned this many degrees from the previous angle.\n  stepAngle = 1 / 10 * tau()\n\n  // Start the decagon sketch at this point.\n  startOfDecagonSketch = startSketchAt([cos(0) * radius, sin(0) * radius])\n\n  // Use a `reduce` to draw the remaining decagon sides.\n  // For each number in the array 1..10, run the given function,\n  // which takes a partially-sketched decagon and adds one more edge to it.\n  fullDecagon = reduce([1..10], startOfDecagonSketch, (i, partialDecagon) => {\n    // Draw one edge of the decagon.\n    x = cos(stepAngle * i) * radius\n    y = sin(stepAngle * i) * radius\n    return lineTo([x, y], partialDecagon)\n})\n\n  return fullDecagon\n}\n\n/* The `decagon` above is basically like this pseudo-code:\nfn decagon(radius):\n    let stepAngle = (1/10) * tau()\n    let startOfDecagonSketch = startSketchAt([(cos(0)*radius), (sin(0) * radius)])\n\n    // Here's the reduce part.\n    let partialDecagon = startOfDecagonSketch\n    for i in [1..10]:\n        let x = cos(stepAngle * i) * radius\n        let y = sin(stepAngle * i) * radius\n        partialDecagon = lineTo([x, y], partialDecagon)\n    fullDecagon = partialDecagon // it's now full\n    return fullDecagon */\n\n\n// Use the `decagon` function declared above, to sketch a decagon with radius 5.\ndecagon(5.0)\n  |> close(%)"
     ]
   },
   {

src/wasm-lib/kcl/src/std/array.rs

@@ -102,26 +102,79 @@ pub async fn reduce(exec_state: &mut ExecState, args: Args) -> Result<KclValue,
 /// Take a starting value. Then, for each element of an array, calculate the next value,
 /// using the previous value and the element.
 /// ```no_run
-/// fn decagon = (radius) => {
-///   let step = (1/10) * tau()
-///   let sketch001 = startSketchAt([(cos(0)*radius), (sin(0) * radius)])
-///   return reduce([1..10], sketch001, (i, sg) => {
-///       let x = cos(step * i) * radius
-///       let y = sin(step * i) * radius
-///       return lineTo([x, y], sg)
-///   })
-/// }
-/// decagon(5.0) |> close(%)
+/// // This function adds two numbers.
+/// fn add = (a, b) => { return a + b }
+///
+/// // This function adds an array of numbers.
+/// // It uses the `reduce` function, to call the `add` function on every
+/// // element of the `array` parameter. The starting value is 0.
+/// fn sum = (array) => { return reduce(array, 0, add) }
+///
+/// /*
+/// The above is basically like this pseudo-code:
+/// fn sum(array):
+///     let sumSoFar = 0
+///     for i in array:
+///         sumSoFar = add(sumSoFar, i)
+///     return sumSoFar
+/// */
+///
+/// // We use `assertEqual` to check that our `sum` function gives the
+/// // expected result. It's good to check your work!
+/// assertEqual(sum([1, 2, 3]), 6, 0.00001, "1 + 2 + 3 summed is 6")
 /// ```
 /// ```no_run
+/// // This example works just like the previous example above, but it uses
+/// // an anonymous `add` function as its parameter, instead of declaring a
+/// // named function outside.
 /// array = [1, 2, 3]
 /// sum = reduce(array, 0, (i, result_so_far) => { return i + result_so_far })
+///
+/// // We use `assertEqual` to check that our `sum` function gives the
+/// // expected result. It's good to check your work!
 /// assertEqual(sum, 6, 0.00001, "1 + 2 + 3 summed is 6")
 /// ```
 /// ```no_run
-/// fn add = (a, b) => { return a + b }
-/// fn sum = (array) => { return reduce(array, 0, add) }
-/// assertEqual(sum([1, 2, 3]), 6, 0.00001, "1 + 2 + 3 summed is 6")
+/// // Declare a function that sketches a decagon.
+/// fn decagon = (radius) => {
+///   // Each side of the decagon is turned this many degrees from the previous angle.
+///   stepAngle = (1/10) * tau()
+///
+///   // Start the decagon sketch at this point.
+///   startOfDecagonSketch = startSketchAt([(cos(0)*radius), (sin(0) * radius)])
+///
+///   // Use a `reduce` to draw the remaining decagon sides.
+///   // For each number in the array 1..10, run the given function,
+///   // which takes a partially-sketched decagon and adds one more edge to it.
+///   fullDecagon = reduce([1..10], startOfDecagonSketch, (i, partialDecagon) => {
+///       // Draw one edge of the decagon.
+///       let x = cos(stepAngle * i) * radius
+///       let y = sin(stepAngle * i) * radius
+///       return lineTo([x, y], partialDecagon)
+///   })
+///
+///   return fullDecagon
+///
+/// }
+///
+/// /*
+/// The `decagon` above is basically like this pseudo-code:
+/// fn decagon(radius):
+///     let stepAngle = (1/10) * tau()
+///     let startOfDecagonSketch = startSketchAt([(cos(0)*radius), (sin(0) * radius)])
+///
+///     // Here's the reduce part.
+///     let partialDecagon = startOfDecagonSketch
+///     for i in [1..10]:
+///         let x = cos(stepAngle * i) * radius
+///         let y = sin(stepAngle * i) * radius
+///         partialDecagon = lineTo([x, y], partialDecagon)
+///     fullDecagon = partialDecagon // it's now full
+///     return fullDecagon
+/// */
+///
+/// // Use the `decagon` function declared above, to sketch a decagon with radius 5.
+/// decagon(5.0) |> close(%)
 /// ```
 #[stdlib {
     name = "reduce",