Update KCL docs

content/pages/docs/kcl-std/functions/std-solver-angle.md

@@ -11,13 +11,17 @@ Constrain lines to meet at a given angle.
 solver::angle(@input: [Segment; 2])
 ```
 
-
+The angle is measured counterclockwise from the first line to the second
+line, modulo 180 degrees, so the order of the lines matters:
+`angle([a, b]) == 30deg` is equivalent to `angle([b, a]) == 150deg`.
+Because the angle is measured modulo 180 degrees, it does not matter
+which end of each line segment is its start or end.
 
 ### Arguments
 
 | Name | Type | Description | Required |
 |----------|------|-------------|----------|
-| `input` | [[`Segment`](/docs/kcl-std/types/std-types-Segment); 2] | The two line segments whose relative angle should match the value set with `==`. | Yes |
+| `input` | [[`Segment`](/docs/kcl-std/types/std-types-Segment); 2] | The two line segments whose relative angle should match the value set with `==`, measured counterclockwise from the first line to the second, modulo 180 degrees. The order of the lines matters. | Yes |
 
 
 ### Examples

content/pages/docs/kcl-std/functions/std-solver-distance.md

@@ -1,11 +1,11 @@
 ---
 title: "solver::distance"
 subtitle: "Function in std::solver"
-excerpt: "Constrain the distance between two points."
+excerpt: "Constrain the distance between two sketch entities."
 layout: manual
 ---
 
-Constrain the distance between two points.
+Constrain the distance between two sketch entities.
 
 ```kcl
 solver::distance(
@@ -14,13 +14,34 @@ solver::distance(
 )
 ```
 
+The distance is always non-negative, and the order of the two entities
+does not matter: `distance([a, b]) == 5mm` and `distance([b, a]) == 5mm`
+are the same constraint. This differs from `horizontalDistance` and
+`verticalDistance`, which are signed and order-sensitive.
 
+Supported entity pairs (in either order):
+
+- Two points: the straight-line distance between them.
+- Point and line: the perpendicular distance from the point to the
+  infinite line through the line segment.
+- Two lines: constrains the lines to be parallel and separated by the
+  given perpendicular distance.
+- Point and circle: the gap between the point and the nearest point on
+  the circle's perimeter, with the point kept outside the circle.
+- Line and circle: the gap between the circle's perimeter and the
+  infinite line through the line segment, with the circle kept to one
+  side of the line.
+- Two circles: the gap between the two perimeters, with each circle kept
+  outside the other.
+
+A point may be `ORIGIN`, and arcs are treated as the full circle through
+them.
 
 ### Arguments
 
 | Name | Type | Description | Required |
 |----------|------|-------------|----------|
-| `points` | [[`Segment`](/docs/kcl-std/types/std-types-Segment) or [`Point2d`](/docs/kcl-std/types/std-types-Point2d); 2] | Two sketch points, or one sketch point and `ORIGIN`, whose separation should match the value set with `==`. | Yes |
+| `points` | [[`Segment`](/docs/kcl-std/types/std-types-Segment) or [`Point2d`](/docs/kcl-std/types/std-types-Point2d); 2] | Two sketch entities, or one sketch entity and `ORIGIN`, whose separation should match the value set with `==`. The order of the entities does not matter. | Yes |
 | `labelPosition` | [`Point2d`](/docs/kcl-std/types/std-types-Point2d) | Optional position for the displayed constraint label in the sketch's local 2D coordinate system. | No |
 
 

content/pages/docs/kcl-std/functions/std-solver-horizontalDistance.md

@@ -14,13 +14,18 @@ solver::horizontalDistance(
 )
 ```
 
-
+The distance is signed, so the order of the points matters: the value set
+with `==` equals the second point's X coordinate minus the first point's
+X coordinate. A positive value places the second point at a greater X
+than the first, and swapping the points negates the sign. For example,
+`horizontalDistance([ORIGIN, point]) == 5mm` places `point` at X = 5mm,
+while `horizontalDistance([point, ORIGIN]) == 5mm` places it at X = -5mm.
 
 ### Arguments
 
 | Name | Type | Description | Required |
 |----------|------|-------------|----------|
-| `points` | [[`Segment`](/docs/kcl-std/types/std-types-Segment) or [`Point2d`](/docs/kcl-std/types/std-types-Point2d); 2] | Two sketch points, or one sketch point and `ORIGIN`, whose X-axis separation should match the value set with `==`. | Yes |
+| `points` | [[`Segment`](/docs/kcl-std/types/std-types-Segment) or [`Point2d`](/docs/kcl-std/types/std-types-Point2d); 2] | Two sketch points, or one sketch point and `ORIGIN`. The value set with `==` equals the second point's X coordinate minus the first point's X coordinate, so the order of the points determines the sign. | Yes |
 | `labelPosition` | [`Point2d`](/docs/kcl-std/types/std-types-Point2d) | Optional position for the displayed constraint label in the sketch's local 2D coordinate system. | No |
 
 

content/pages/docs/kcl-std/functions/std-solver-verticalDistance.md

@@ -14,13 +14,18 @@ solver::verticalDistance(
 )
 ```
 
-
+The distance is signed, so the order of the points matters: the value set
+with `==` equals the second point's Y coordinate minus the first point's
+Y coordinate. A positive value places the second point at a greater Y
+than the first, and swapping the points negates the sign. For example,
+`verticalDistance([ORIGIN, point]) == 5mm` places `point` at Y = 5mm,
+while `verticalDistance([point, ORIGIN]) == 5mm` places it at Y = -5mm.
 
 ### Arguments
 
 | Name | Type | Description | Required |
 |----------|------|-------------|----------|
-| `points` | [[`Segment`](/docs/kcl-std/types/std-types-Segment) or [`Point2d`](/docs/kcl-std/types/std-types-Point2d); 2] | Two sketch points, or one sketch point and `ORIGIN`, whose Y-axis separation should match the value set with `==`. | Yes |
+| `points` | [[`Segment`](/docs/kcl-std/types/std-types-Segment) or [`Point2d`](/docs/kcl-std/types/std-types-Point2d); 2] | Two sketch points, or one sketch point and `ORIGIN`. The value set with `==` equals the second point's Y coordinate minus the first point's Y coordinate, so the order of the points determines the sign. | Yes |
 | `labelPosition` | [`Point2d`](/docs/kcl-std/types/std-types-Point2d) | Optional position for the displayed constraint label in the sketch's local 2D coordinate system. | No |
 
 

content/pages/docs/kcl-std/functions/std-string-toString.md

@@ -0,0 +1,65 @@
+---
+title: "string::toString"
+subtitle: "Function in std::string"
+excerpt: "Convert a number to human-readable text."
+layout: manual
+---
+
+Convert a number to human-readable text.
+
+```kcl
+string::toString(@num: number): string
+```
+
+Defined for every [`number`](/docs/kcl-std/types/std-types-number) value, including the non-finite ones.
+
+| Value | Result | Why |
+|---|---|---|
+| `12` | `"12"` | no units, so no suffix |
+| `1.5` | `"1.5"` | never rounded |
+| `0.1 + 0.2` | `"0.30000000000000004"` | no digits are dropped |
+| `-7` | `"-7"` | |
+| `-0` | `"0"` | the sign of zero is not kept |
+| `3_` | `"3_"` | a count keeps its `_` |
+| `12mm` | `"12mm"` | a concrete length keeps its suffix |
+| `12cm`, `12m`, `1.5in`, `2ft`, `3yd` | `"12cm"`, `"12m"`, `"1.5in"`, `"2ft"`, `"3yd"` | every length unit does |
+| `90deg` | `"90deg"` | a concrete angle keeps its suffix |
+| `1.5rad` | `"1.5rad"` | both angle units do |
+| `2mm + 10mm` | `"12mm"` | arithmetic that keeps its units |
+| `2mm * 10mm` | `"20"` | units no longer tracked, so none is shown |
+| `1 / 0` | `"Infinity"` | |
+| `-1 / 0` | `"-Infinity"` | |
+| `0 / 0` | `"NaN"` | |
+| `1mm / 0` | `"Infinity"` | a non-finite value never carries a unit |
+
+The output is meant to be read, not parsed. Some results are not valid KCL
+source and reading one back is not supported.
+
+### Arguments
+
+| Name | Type | Description | Required |
+|----------|------|-------------|----------|
+| `num` | [`number`](/docs/kcl-std/types/std-types-number) | The number to convert. | Yes |
+
+### Returns
+
+[`string`](/docs/kcl-std/types/std-types-string) - A sequence of characters
+
+
+### Examples
+
+```kcl
+lengthText = 12mm
+  |> string::toString()
+
+assertIs(lengthText == "12mm")
+
+countText = string::toString(3_)
+
+assertIs(countText == "3_")
+
+```
+
+
+
+

content/pages/docs/kcl-std/functions/std-vector-add.md

@@ -1,11 +1,11 @@
 ---
 title: "vector::add"
 subtitle: "Function in std::vector"
-excerpt: "Adds every element of u to its corresponding element in v. Both vectors must have the same length. Returns a new vector of the same length. In other words, component-wise addition."
+excerpt: "Adds every element of u to its corresponding element in v. Both vectors must have the same number of elements. Returns a new vector with the same number of elements. In other words, component-wise addition."
 layout: manual
 ---
 
-Adds every element of u to its corresponding element in v. Both vectors must have the same length. Returns a new vector of the same length. In other words, component-wise addition.
+Adds every element of u to its corresponding element in v. Both vectors must have the same number of elements. Returns a new vector with the same number of elements. In other words, component-wise addition.
 
 ```kcl
 vector::add(

content/pages/docs/kcl-std/functions/std-vector-div.md

@@ -1,11 +1,11 @@
 ---
 title: "vector::div"
 subtitle: "Function in std::vector"
-excerpt: "Divides every element of u by its corresponding element in v. Both vectors must have the same length. Returns a new vector of the same length. In other words, component-wise division."
+excerpt: "Divides every element of u by its corresponding element in v. Both vectors must have the same number of elements. Returns a new vector with the same number of elements. In other words, component-wise division."
 layout: manual
 ---
 
-Divides every element of u by its corresponding element in v. Both vectors must have the same length. Returns a new vector of the same length. In other words, component-wise division.
+Divides every element of u by its corresponding element in v. Both vectors must have the same number of elements. Returns a new vector with the same number of elements. In other words, component-wise division.
 
 ```kcl
 vector::div(

content/pages/docs/kcl-std/functions/std-vector-mul.md

@@ -1,11 +1,11 @@
 ---
 title: "vector::mul"
 subtitle: "Function in std::vector"
-excerpt: "Multiplies every element of u by its corresponding element in v. Both vectors must have the same length. Returns a new vector of the same length. In other words, component-wise multiplication."
+excerpt: "Multiplies every element of u by its corresponding element in v. Both vectors must have the same number of elements. Returns a new vector with the same number of elements. In other words, component-wise multiplication."
 layout: manual
 ---
 
-Multiplies every element of u by its corresponding element in v. Both vectors must have the same length. Returns a new vector of the same length. In other words, component-wise multiplication.
+Multiplies every element of u by its corresponding element in v. Both vectors must have the same number of elements. Returns a new vector with the same number of elements. In other words, component-wise multiplication.
 
 ```kcl
 vector::mul(

content/pages/docs/kcl-std/functions/std-vector-sub.md

@@ -1,11 +1,11 @@
 ---
 title: "vector::sub"
 subtitle: "Function in std::vector"
-excerpt: "Subtracts from every element of u its corresponding element in v. Both vectors must have the same length. Returns a new vector of the same length. In other words, component-wise subtraction."
+excerpt: "Subtracts from every element of u its corresponding element in v. Both vectors must have the same number of elements. Returns a new vector with the same number of elements. In other words, component-wise subtraction."
 layout: manual
 ---
 
-Subtracts from every element of u its corresponding element in v. Both vectors must have the same length. Returns a new vector of the same length. In other words, component-wise subtraction.
+Subtracts from every element of u its corresponding element in v. Both vectors must have the same number of elements. Returns a new vector with the same number of elements. In other words, component-wise subtraction.
 
 ```kcl
 vector::sub(

content/pages/docs/kcl-std/index.md

@@ -190,6 +190,7 @@ layout: manual
 * [**std::string**](/docs/kcl-std/modules/std-string)
   * [`string::isEqual`](/docs/kcl-std/functions/std-string-isEqual)
   * [`string::lowercase`](/docs/kcl-std/functions/std-string-lowercase)
+  * [`string::toString`](/docs/kcl-std/functions/std-string-toString)
   * [`string::trim`](/docs/kcl-std/functions/std-string-trim)
   * [`string::trimEnd`](/docs/kcl-std/functions/std-string-trimEnd)
   * [`string::trimStart`](/docs/kcl-std/functions/std-string-trimStart)

content/pages/docs/kcl-std/modules/std-string.md

@@ -16,6 +16,7 @@ their contents.
 
 * [`string::isEqual`](/docs/kcl-std/functions/std-string-isEqual)
 * [`string::lowercase`](/docs/kcl-std/functions/std-string-lowercase)
+* [`string::toString`](/docs/kcl-std/functions/std-string-toString)
 * [`string::trim`](/docs/kcl-std/functions/std-string-trim)
 * [`string::trimEnd`](/docs/kcl-std/functions/std-string-trimEnd)
 * [`string::trimStart`](/docs/kcl-std/functions/std-string-trimStart)