better docs on solids and sketches (#5428)

* updates

Signed-off-by: Jess Frazelle <github@jessfraz.com>

* fix docs;

Signed-off-by: Jess Frazelle <github@jessfraz.com>

* updates

Signed-off-by: Jess Frazelle <github@jessfraz.com>

* updates

Signed-off-by: Jess Frazelle <github@jessfraz.com>

* updates

Signed-off-by: Jess Frazelle <github@jessfraz.com>

* updates

Signed-off-by: Jess Frazelle <github@jessfraz.com>

* updates

Signed-off-by: Jess Frazelle <github@jessfraz.com>

* updates

Signed-off-by: Jess Frazelle <github@jessfraz.com>

* updates

Signed-off-by: Jess Frazelle <github@jessfraz.com>

* updates

Signed-off-by: Jess Frazelle <github@jessfraz.com>

* parens

Signed-off-by: Jess Frazelle <github@jessfraz.com>

* parens

Signed-off-by: Jess Frazelle <github@jessfraz.com>

---------

Signed-off-by: Jess Frazelle <github@jessfraz.com>

docs/kcl/chamfer.md

@@ -18,12 +18,12 @@ chamfer(data: ChamferData, solid: Solid, tag?: TagDeclarator) -> Solid
 | Name | Type | Description | Required |
 |----------|------|-------------|----------|
 | `data` | [`ChamferData`](/docs/kcl/types/ChamferData) | Data for chamfers. | Yes |
-| `solid` | [`Solid`](/docs/kcl/types/Solid) | An solid is a collection of extrude surfaces. | Yes |
+| `solid` | [`Solid`](/docs/kcl/types/Solid) | A solid is a collection of extrude surfaces. | Yes |
 | `tag` | [`TagDeclarator`](/docs/kcl/types#tag-declaration) |  | No |
 
 ### Returns
 
-[`Solid`](/docs/kcl/types/Solid) - An solid is a collection of extrude surfaces.
+[`Solid`](/docs/kcl/types/Solid) - A solid is a collection of extrude surfaces.
 
 
 ### Examples

docs/kcl/fillet.md

@@ -18,12 +18,12 @@ fillet(data: FilletData, solid: Solid, tag?: TagDeclarator) -> Solid
 | Name | Type | Description | Required |
 |----------|------|-------------|----------|
 | `data` | [`FilletData`](/docs/kcl/types/FilletData) | Data for fillets. | Yes |
-| `solid` | [`Solid`](/docs/kcl/types/Solid) | An solid is a collection of extrude surfaces. | Yes |
+| `solid` | [`Solid`](/docs/kcl/types/Solid) | A solid is a collection of extrude surfaces. | Yes |
 | `tag` | [`TagDeclarator`](/docs/kcl/types#tag-declaration) |  | No |
 
 ### Returns
 
-[`Solid`](/docs/kcl/types/Solid) - An solid is a collection of extrude surfaces.
+[`Solid`](/docs/kcl/types/Solid) - A solid is a collection of extrude surfaces.
 
 
 ### Examples

docs/kcl/helixRevolutions.md

@@ -18,11 +18,11 @@ helixRevolutions(data: HelixRevolutionsData, solid: Solid) -> Solid
 | Name | Type | Description | Required |
 |----------|------|-------------|----------|
 | `data` | [`HelixRevolutionsData`](/docs/kcl/types/HelixRevolutionsData) | Data for helix revolutions. | Yes |
-| `solid` | [`Solid`](/docs/kcl/types/Solid) | An solid is a collection of extrude surfaces. | Yes |
+| `solid` | [`Solid`](/docs/kcl/types/Solid) | A solid is a collection of extrude surfaces. | Yes |
 
 ### Returns
 
-[`Solid`](/docs/kcl/types/Solid) - An solid is a collection of extrude surfaces.
+[`Solid`](/docs/kcl/types/Solid) - A solid is a collection of extrude surfaces.
 
 
 ### Examples

docs/kcl/hollow.md

@@ -18,11 +18,11 @@ hollow(thickness: number, solid: Solid) -> Solid
 | Name | Type | Description | Required |
 |----------|------|-------------|----------|
 | `thickness` | `number` |  | Yes |
-| `solid` | [`Solid`](/docs/kcl/types/Solid) | An solid is a collection of extrude surfaces. | Yes |
+| `solid` | [`Solid`](/docs/kcl/types/Solid) | A solid is a collection of extrude surfaces. | Yes |
 
 ### Returns
 
-[`Solid`](/docs/kcl/types/Solid) - An solid is a collection of extrude surfaces.
+[`Solid`](/docs/kcl/types/Solid) - A solid is a collection of extrude surfaces.
 
 
 ### Examples

docs/kcl/loft.md

@@ -25,7 +25,7 @@ loft(sketches: [Sketch], v_degree: NonZeroU32, bez_approximate_rational: bool, b
 
 ### Returns
 
-[`Solid`](/docs/kcl/types/Solid) - An solid is a collection of extrude surfaces.
+[`Solid`](/docs/kcl/types/Solid) - A solid is a collection of extrude surfaces.
 
 
 ### Examples

docs/kcl/revolve.md

@@ -24,7 +24,7 @@ revolve(data: RevolveData, sketch: Sketch) -> Solid
 
 ### Returns
 
-[`Solid`](/docs/kcl/types/Solid) - An solid is a collection of extrude surfaces.
+[`Solid`](/docs/kcl/types/Solid) - A solid is a collection of extrude surfaces.
 
 
 ### Examples

docs/kcl/sweep.md

@@ -24,7 +24,7 @@ sweep(sketch: Sketch, path: SweepPath, sectional?: bool, tolerance?: number) ->
 
 ### Returns
 
-[`Solid`](/docs/kcl/types/Solid) - An solid is a collection of extrude surfaces.
+[`Solid`](/docs/kcl/types/Solid) - A solid is a collection of extrude surfaces.
 
 
 ### Examples

docs/kcl/types/NumericType.md

@@ -33,6 +33,7 @@ layout: manual
 
 
 ----
+A unit of length.
 
 **Type:** `object`
 
@@ -140,6 +141,7 @@ layout: manual
 
 
 ----
+A unit of angle.
 
 **Type:** `object`
 

docs/kcl/types/Sketch.md

@@ -6,6 +6,40 @@ layout: manual
 
 A sketch is a collection of paths.
 
+When you define a sketch to a variable like:
+
+```kcl
+mySketch = startSketchOn('XY')
+  |> startProfileAt([-12, 12], %)
+  |> line(end = [24, 0])
+  |> line(end = [0, -24])
+  |> line(end = [-24, 0])
+  |> close()
+```
+
+The `mySketch` variable will be an executed [`Sketch`](/docs/kcl/types/Sketch) object. Executed being past tense, because the engine has already executed the commands to create the sketch.
+
+The previous sketch commands will never be executed again, in this case.
+
+If you would like to encapsulate the commands to create the sketch any time you call it, you can use a function.
+
+```kcl
+fn createSketch() {
+  return startSketchOn('XY')
+    |> startProfileAt([-12, 12], %)
+    |> line(end = [24, 0])
+    |> line(end = [0, -24])
+    |> line(end = [-24, 0])
+    |> close()
+}
+```
+
+Now, every time you call `createSketch()`, the commands will be executed and a new sketch will be created.
+
+When you assign the result of `createSketch()` to a variable (`mySketch = createSketch()`), you are assigning the executed sketch to that variable. Meaning that the sketch `mySketch` will not be executed again.
+
+You can still execute _new_ commands on the sketch like `extrude`, `revolve`, `loft`, etc. and the sketch will be updated.
+
 **Type:** `object`
 
 

docs/kcl/types/SketchSet.md

@@ -14,6 +14,40 @@ A sketch or a group of sketches.
 
 A sketch is a collection of paths.
 
+When you define a sketch to a variable like:
+
+```kcl
+mySketch = startSketchOn('XY')
+  |> startProfileAt([-12, 12], %)
+  |> line(end = [24, 0])
+  |> line(end = [0, -24])
+  |> line(end = [-24, 0])
+  |> close()
+```
+
+The `mySketch` variable will be an executed [`Sketch`](/docs/kcl/types/Sketch) object. Executed being past tense, because the engine has already executed the commands to create the sketch.
+
+The previous sketch commands will never be executed again, in this case.
+
+If you would like to encapsulate the commands to create the sketch any time you call it, you can use a function.
+
+```kcl
+fn createSketch() {
+  return startSketchOn('XY')
+    |> startProfileAt([-12, 12], %)
+    |> line(end = [24, 0])
+    |> line(end = [0, -24])
+    |> line(end = [-24, 0])
+    |> close()
+}
+```
+
+Now, every time you call `createSketch()`, the commands will be executed and a new sketch will be created.
+
+When you assign the result of `createSketch()` to a variable (`mySketch = createSketch()`), you are assigning the executed sketch to that variable. Meaning that the sketch `mySketch` will not be executed again.
+
+You can still execute _new_ commands on the sketch like `extrude`, `revolve`, `loft`, etc. and the sketch will be updated.
+
 **Type:** `object`
 
 

docs/kcl/types/Solid.md

@@ -1,10 +1,46 @@
 ---
 title: "Solid"
-excerpt: "An solid is a collection of extrude surfaces."
+excerpt: "A solid is a collection of extrude surfaces."
 layout: manual
 ---
 
-An solid is a collection of extrude surfaces.
+A solid is a collection of extrude surfaces.
+
+When you define a solid to a variable like:
+
+```kcl
+myPart = startSketchOn('XY')
+  |> startProfileAt([-12, 12], %)
+  |> line(end = [24, 0])
+  |> line(end = [0, -24])
+  |> line(end = [-24, 0])
+  |> close()
+  |> extrude(length = 6)
+```
+
+The `myPart` variable will be an executed [`Solid`](/docs/kcl/types/Solid) object. Executed being past tense, because the engine has already executed the commands to create the solid.
+
+The previous solid commands will never be executed again, in this case.
+
+If you would like to encapsulate the commands to create the solid any time you call it, you can use a function.
+
+```kcl
+fn createPart() {
+  return startSketchOn('XY')
+    |> startProfileAt([-12, 12], %)
+    |> line(end = [24, 0])
+    |> line(end = [0, -24])
+    |> line(end = [-24, 0])
+    |> close()
+    |> extrude(length = 6)
+}
+```
+
+Now, every time you call `createPart()`, the commands will be executed and a new solid will be created.
+
+When you assign the result of `createPart()` to a variable (`myPart = createPart()`), you are assigning the executed solid to that variable. Meaning that the solid `myPart` will not be executed again.
+
+You can still execute _new_ commands on the solid like `shell`, `fillet`, `chamfer`, etc. and the solid will be updated.
 
 **Type:** `object`
 
@@ -24,7 +60,7 @@ An solid is a collection of extrude surfaces.
 | `startCapId` |`string`| The id of the extrusion start cap | No |
 | `endCapId` |`string`| The id of the extrusion end cap | No |
 | `edgeCuts` |`[` [`EdgeCut`](/docs/kcl/types/EdgeCut) `]`| Chamfers or fillets on this solid. | No |
-| `units` |[`UnitLen`](/docs/kcl/types/UnitLen)| An solid is a collection of extrude surfaces. | No |
+| `units` |[`UnitLen`](/docs/kcl/types/UnitLen)| A solid is a collection of extrude surfaces. | No |
 | `__meta` |`[` [`Metadata`](/docs/kcl/types/Metadata) `]`| Metadata. | No |
 
 

docs/kcl/types/SolidSet.md

@@ -12,7 +12,43 @@ A solid or a group of solids.
 
 **This schema accepts exactly one of the following:**
 
-An solid is a collection of extrude surfaces.
+A solid is a collection of extrude surfaces.
+
+When you define a solid to a variable like:
+
+```kcl
+myPart = startSketchOn('XY')
+  |> startProfileAt([-12, 12], %)
+  |> line(end = [24, 0])
+  |> line(end = [0, -24])
+  |> line(end = [-24, 0])
+  |> close()
+  |> extrude(length = 6)
+```
+
+The `myPart` variable will be an executed [`Solid`](/docs/kcl/types/Solid) object. Executed being past tense, because the engine has already executed the commands to create the solid.
+
+The previous solid commands will never be executed again, in this case.
+
+If you would like to encapsulate the commands to create the solid any time you call it, you can use a function.
+
+```kcl
+fn createPart() {
+  return startSketchOn('XY')
+    |> startProfileAt([-12, 12], %)
+    |> line(end = [24, 0])
+    |> line(end = [0, -24])
+    |> line(end = [-24, 0])
+    |> close()
+    |> extrude(length = 6)
+}
+```
+
+Now, every time you call `createPart()`, the commands will be executed and a new solid will be created.
+
+When you assign the result of `createPart()` to a variable (`myPart = createPart()`), you are assigning the executed solid to that variable. Meaning that the solid `myPart` will not be executed again.
+
+You can still execute _new_ commands on the solid like `shell`, `fillet`, `chamfer`, etc. and the solid will be updated.
 
 **Type:** `object`
 

docs/kcl/types/UnitAngle.md

@@ -1,9 +1,10 @@
 ---
 title: "UnitAngle"
-excerpt: ""
+excerpt: "A unit of angle."
 layout: manual
 ---
 
+A unit of angle.
 
 
 

docs/kcl/types/UnitLen.md

@@ -1,9 +1,10 @@
 ---
 title: "UnitLen"
-excerpt: ""
+excerpt: "A unit of length."
 layout: manual
 ---
 
+A unit of length.