Make the function signature less prominent, add an early example to docs

docs/kcl-std/functions/std-appearance-hexString.md

@@ -8,10 +8,12 @@ layout: manual
 Build a color from its red, green and blue components. These must be between 0 and 255.
 
 ```kcl
-appearance::hexString(@rgb: [number(_); 3]): string
-```
-
+startSketchOn(-XZ)
+  |> circle(center = [0, 0], radius = 10)
+  |> extrude(length = 4)
+  |> appearance(color = appearance::hexString([50, 160, 160]))
 
+```
 
 ### Arguments
 
@@ -24,6 +26,12 @@ appearance::hexString(@rgb: [number(_); 3]): string
 [`string`](/docs/kcl-std/types/std-types-string) - A sequence of characters
 
 
+### Function signature
+
+```kcl
+appearance::hexString(@rgb: [number(_); 3]): string
+```
+
 ### Examples
 
 ```kcl

docs/kcl-std/functions/std-array-map.md

@@ -8,14 +8,18 @@ layout: manual
 Apply a function to every element of a list.
 
 ```kcl
-map(
-  @array: [any],
-  f: fn(any): any,
-): [any]
-```
+r = 10 // radius
+fn drawCircle(@id) {
+  return startSketchOn(XY)
+    |> circle(center = [id * 2 * r, 0], radius = r)
+}
 
-Given a list like `[a, b, c]`, and a function like `f`, returns
-`[f(a), f(b), f(c)]`
+// Call `drawCircle`, passing in each element of the array.
+// The outputs from each `drawCircle` form a new array,
+// which is the return value from `map`.
+circles = map([1..3], f = drawCircle)
+
+```
 
 ### Arguments
 
@@ -28,6 +32,19 @@ Given a list like `[a, b, c]`, and a function like `f`, returns
 
 [`[any]`](/docs/kcl-std/types/std-types-any)
 
+### Description
+
+Given a list like `[a, b, c]`, and a function like `f`, returns
+`[f(a), f(b), f(c)]`
+
+### Function signature
+
+```kcl
+map(
+  @array: [any],
+  f: fn(any): any,
+): [any]
+```
 
 ### Examples
 

docs/kcl-std/functions/std-array-pop.md

@@ -8,10 +8,28 @@ layout: manual
 Remove the last element from an array.
 
 ```kcl
-pop(@array: [any; 1+]): [any]
-```
+arr = [1, 2, 3, 4]
+new_arr = pop(arr)
+assert(
+  new_arr[0],
+  isEqualTo = 1,
+  tolerance = 0.00001,
+  error = "1 is the first element of the array",
+)
+assert(
+  new_arr[1],
+  isEqualTo = 2,
+  tolerance = 0.00001,
+  error = "2 is the second element of the array",
+)
+assert(
+  new_arr[2],
+  isEqualTo = 3,
+  tolerance = 0.00001,
+  error = "3 is the third element of the array",
+)
 
-Returns a new array with the last element removed.
+```
 
 ### Arguments
 
@@ -23,6 +41,15 @@ Returns a new array with the last element removed.
 
 [`[any]`](/docs/kcl-std/types/std-types-any)
 
+### Description
+
+Returns a new array with the last element removed.
+
+### Function signature
+
+```kcl
+pop(@array: [any; 1+]): [any]
+```
 
 ### Examples
 

docs/kcl-std/functions/std-array-push.md

@@ -8,13 +8,16 @@ layout: manual
 Append an element to the end of an array.
 
 ```kcl
-push(
-  @array: [any],
-  item: any,
-): [any; 1+]
-```
+arr = [1, 2, 3]
+new_arr = push(arr, item = 4)
+assert(
+  new_arr[3],
+  isEqualTo = 4,
+  tolerance = 0.1,
+  error = "4 was added to the end of the array",
+)
 
-Returns a new array with the element appended.
+```
 
 ### Arguments
 
@@ -27,6 +30,18 @@ Returns a new array with the element appended.
 
 [`[any; 1+]`](/docs/kcl-std/types/std-types-any)
 
+### Description
+
+Returns a new array with the element appended.
+
+### Function signature
+
+```kcl
+push(
+  @array: [any],
+  item: any,
+): [any; 1+]
+```
 
 ### Examples
 

docs/kcl-std/functions/std-array-reduce.md

@@ -8,14 +8,35 @@ layout: manual
 Take a starting value. Then, for each element of an array, calculate the next value, using the previous value and the element.
 
 ```kcl
-reduce(
-  @array: [any],
-  initial: any,
-  f: fn(any, accum: any): any,
-): any
-```
+// This function adds two numbers.
+fn add(@a, accum) {
+  return a + accum
+}
+
+// This function adds an array of numbers.
+// It uses the `reduce` function, to call the `add` function on every
+// element of the `arr` parameter. The starting value is 0.
+fn sum(@arr) {
+  return reduce(arr, initial = 0, f = add)
+}
+
+/* The above is basically like this pseudo-code:
+fn sum(arr):
+    sumSoFar = 0
+    for i in arr:
+        sumSoFar = add(i, sumSoFar)
+    return sumSoFar */
 
+// We use `assert` to check that our `sum` function gives the
+// expected result. It's good to check your work!
+assert(
+  sum([1, 2, 3]),
+  isEqualTo = 6,
+  tolerance = 0.1,
+  error = "1 + 2 + 3 summed is 6",
+)
 
+```
 
 ### Arguments
 
@@ -30,6 +51,16 @@ reduce(
 [`any`](/docs/kcl-std/types/std-types-any) - The [`any`](/docs/kcl-std/types/std-types-any) type is the type of all possible values in KCL. I.e., if a function accepts an argument with type [`any`](/docs/kcl-std/types/std-types-any), then it can accept any value.
 
 
+### Function signature
+
+```kcl
+reduce(
+  @array: [any],
+  initial: any,
+  f: fn(any, accum: any): any,
+): any
+```
+
 ### Examples
 
 ```kcl

docs/kcl-std/functions/std-assert.md

@@ -8,19 +8,22 @@ layout: manual
 Check a value meets some expected conditions at runtime. Program terminates with an error if conditions aren't met. If you provide multiple conditions, they will all be checked and all must be met.
 
 ```kcl
+n = 10
+assert(n, isEqualTo = 10)
 assert(
-  @actual: number,
-  isGreaterThan?: number,
-  isLessThan?: number,
-  isGreaterThanOrEqual?: number,
-  isLessThanOrEqual?: number,
-  isEqualTo?: number,
-  tolerance?: number,
-  error?: string,
+  n,
+  isGreaterThanOrEqual = 0,
+  isLessThan = 100,
+  error = "number should be between 0 and 100",
+)
+assert(
+  1.0000000000012,
+  isEqualTo = 1,
+  tolerance = 0.0001,
+  error = "number should be almost exactly 1",
 )
-```
-
 
+```
 
 ### Arguments
 
@@ -36,6 +39,21 @@ assert(
 | `error` | [`string`](/docs/kcl-std/types/std-types-string) | If the value was false, the program will terminate with this error message | No |
 
 
+### Function signature
+
+```kcl
+assert(
+  @actual: number,
+  isGreaterThan?: number,
+  isLessThan?: number,
+  isGreaterThanOrEqual?: number,
+  isLessThanOrEqual?: number,
+  isEqualTo?: number,
+  tolerance?: number,
+  error?: string,
+)
+```
+
 ### Examples
 
 ```kcl

docs/kcl-std/functions/std-assertIs.md

@@ -8,13 +8,10 @@ layout: manual
 Asserts that a value is the boolean value true.
 
 ```kcl
-assertIs(
-  @actual: bool,
-  error?: string,
-)
-```
-
+kclIsFun = true
+assertIs(kclIsFun)
 
+```
 
 ### Arguments
 
@@ -24,6 +21,15 @@ assertIs(
 | `error` | [`string`](/docs/kcl-std/types/std-types-string) | If the value was false, the program will terminate with this error message | No |
 
 
+### Function signature
+
+```kcl
+assertIs(
+  @actual: bool,
+  error?: string,
+)
+```
+
 ### Examples
 
 ```kcl

docs/kcl-std/functions/std-clone.md

@@ -8,17 +8,20 @@ layout: manual
 Clone a sketch or solid.
 
 ```kcl
-clone(@geometry: Sketch | Solid | ImportedGeometry): Sketch | Solid | ImportedGeometry
-```
-
-This works essentially like a copy-paste operation. It creates a perfect replica
-at that point in time that you can manipulate individually afterwards.
+// Clone a basic sketch and move it and extrude it.
+exampleSketch = startSketchOn(XY)
+  |> startProfile(at = [0, 0])
+  |> line(end = [10, 0])
+  |> line(end = [0, 10])
+  |> line(end = [-10, 0])
+  |> close()
 
-This doesn't really have much utility unless you need the equivalent of a double
-instance pattern with zero transformations.
+clonedSketch = clone(exampleSketch)
+  |> scale(x = 1.0, y = 1.0, z = 2.5)
+  |> translate(x = 15.0, y = 0, z = 0)
+  |> extrude(length = 5)
 
-Really only use this function if YOU ARE SURE you need it. In most cases you
-do not need clone and using a pattern with `instance = 2` is more appropriate.
+```
 
 ### Arguments
 
@@ -30,6 +33,22 @@ do not need clone and using a pattern with `instance = 2` is more appropriate.
 
 [`Sketch`](/docs/kcl-std/types/std-types-Sketch) or [`Solid`](/docs/kcl-std/types/std-types-Solid) or [`ImportedGeometry`](/docs/kcl-std/types/std-types-ImportedGeometry)
 
+### Description
+
+This works essentially like a copy-paste operation. It creates a perfect replica
+at that point in time that you can manipulate individually afterwards.
+
+This doesn't really have much utility unless you need the equivalent of a double
+instance pattern with zero transformations.
+
+Really only use this function if YOU ARE SURE you need it. In most cases you
+do not need clone and using a pattern with `instance = 2` is more appropriate.
+
+### Function signature
+
+```kcl
+clone(@geometry: Sketch | Solid | ImportedGeometry): Sketch | Solid | ImportedGeometry
+```
 
 ### Examples