Docs content (#6792)

* Add documentation to modules, and some constants and types

Signed-off-by: Nick Cameron <nrc@ncameron.org>

* Improve the language reference

Signed-off-by: Nick Cameron <nrc@ncameron.org>

---------

Signed-off-by: Nick Cameron <nrc@ncameron.org>

rust/kcl-lib/std/array.kcl

@@ -1,2 +1,4 @@
+/// Functions for manipulating arrays of values.
+
 @no_std
 @settings(defaultLengthUnit = mm, kclVersion = 1.0)

rust/kcl-lib/std/math.kcl

@@ -1,3 +1,5 @@
+/// Functions for mathematical operations and some useful constants.
+
 @no_std
 @settings(defaultLengthUnit = mm, kclVersion = 1.0)
 

rust/kcl-lib/std/prelude.kcl

@@ -2,6 +2,9 @@
 ///
 /// Contains frequently used constants, functions for interacting with the KittyCAD servers to
 /// create sketches and geometry, and utility functions.
+///
+/// The standard library is organised into modules (listed below), but most things are always available
+/// in KCL programs.
 
 @no_std
 @settings(defaultLengthUnit = mm, kclVersion = 1.0)
@@ -17,34 +20,40 @@ export import * from "std::solid"
 export import * from "std::transform"
 export import "std::turns"
 
+/// An abstract 3d plane aligned with the X and Y axes. Its normal is the positive Z axis.
 export XY = {
   origin = { x = 0, y = 0, z = 0 },
   xAxis = { x = 1, y = 0, z = 0 },
   yAxis = { x = 0, y = 1, z = 0 },
 }: Plane
 
+/// An abstract 3d plane aligned with the X and Z axes. Its normal is the negative Y axis.
 export XZ = {
   origin = { x = 0, y = 0, z = 0 },
   xAxis = { x = 1, y = 0, z = 0 },
   yAxis = { x = 0, y = 0, z = 1 },
 }: Plane
 
+/// An abstract 3d plane aligned with the Y and Z axes. Its normal is the positive X axis.
 export YZ = {
   origin = { x = 0, y = 0, z = 0 },
   xAxis = { x = 0, y = 1, z = 0 },
   yAxis = { x = 0, y = 0, z = 1 },
 }: Plane
 
+/// The X-axis (can be used in both 2d and 3d contexts).
 export X = {
   origin = [0, 0, 0],
   direction = [1, 0, 0],
 }: Axis3d
 
+/// The Y-axis (can be used in both 2d and 3d contexts).
 export Y = {
   origin = [0, 0, 0],
   direction = [0, 1, 0],
 }: Axis3d
 
+/// The 3D Z-axis.
 export Z = {
   origin = [0, 0, 0],
   direction = [0, 0, 1],

rust/kcl-lib/std/sketch.kcl

@@ -1,3 +1,9 @@
+/// Sketching is the foundational activity for most KCL programs. A sketch is a two-dimensional
+/// drawing made from paths or shapes. A sketch is always drawn on a surface (either an abstract
+/// plane of a face of a solid). A sketch can be made into a solid by extruding it (or revolving, etc.).
+///
+/// This module contains functions for creating and manipulating sketches, and making them into solids.
+
 @no_std
 @settings(defaultLengthUnit = mm, kclVersion = 1.0)
 

rust/kcl-lib/std/solid.kcl

@@ -1,3 +1,6 @@
+/// This module contains functions for modifying solids, e.g., by adding a fillet or chamfer, or
+/// removing part of a solid.
+
 @no_std
 @settings(defaultLengthUnit = mm, kclVersion = 1.0)
 

rust/kcl-lib/std/transform.kcl

@@ -1,7 +1,8 @@
+/// This module contains functions for transforming sketches and solids.
+
 @no_std
 @settings(defaultLengthUnit = mm, kclVersion = 1.0)
 
-
 /// Mirror a sketch.
 ///
 /// Only works on unclosed sketches for now.

rust/kcl-lib/std/turns.kcl

@@ -1,7 +1,16 @@
+/// This module contains a few handy constants for defining turns.
+
 @no_std
 @settings(defaultLengthUnit = mm, kclVersion = 1.0)
 
+/// No turn, zero degrees/radians.
 export ZERO = 0
+
+/// A quarter turn, 90 degrees or π/2 radians.
 export QUARTER_TURN = 90deg
+
+/// A half turn, 180 degrees or π radians.
 export HALF_TURN = 180deg
+
+/// Three quarters of a turn, 270 degrees or 1.5*π radians.
 export THREE_QUARTER_TURN = 270deg

rust/kcl-lib/std/types.kcl

@@ -1,21 +1,52 @@
+/// KCL types. This module contains fundamental types like `number`, `string`, `Solid`, and `Sketch`.
+///
+/// Types can (optionally) be used to describe a function's arguments and returned value. They are checked
+/// when a program runs and can help avoid errors. They are also useful to help document what a function
+/// does.
+
 @no_std
 @settings(defaultLengthUnit = mm, kclVersion = 1.0)
 
-/// Any value.
+/// The `any` type is the type of all possible values in KCL. I.e., if a function accepts an argument
+/// with type `any`, then it can accept any value.
+///
+/// ```kcl,norun
+/// fn acceptAnything(@input: any) {
+///   return true
+/// }
+///
+/// acceptAnything(42)
+/// acceptAnything('hello')
+/// acceptAnything(XY)
+/// acceptAnything([0, 1, 2])
+/// ```
 @(impl = primitive)
 export type any
 
-/// A number
+/// A number.
 ///
 /// May be signed or unsigned, an integer or decimal value.
 ///
-/// You may see a number type with units, e.g., `number(mm)`. These are currently experimental.
+/// KCL numbers always include units, e.g., the number `42` is always '42 mm' or '42 degrees', etc.
+/// it is never just '42'. The `number` type may or may not include units, if none are specified, then
+/// it is the type of any number. E.g.,
+///
+/// - `number`: the type of any numbers,
+/// - `number(mm)`: the type of numbers in millimeters,
+/// - `number(in)`: the type of numbers in inches,
+/// - `number(Length)`: the type of numbers in any length unit,
+/// - `number(deg)`: the type of numbers in degrees,
+/// - `number(Angle)`: the type of numbers in any angle unit,
+/// - `number(_)` or `number(Count)`: the type of unit-less numbers, representing a count of things,
+/// or a ratio, etc.
+///
+/// For more information, see [numeric types](/docs/kcl-lang/numeric).
 @(impl = primitive)
 export type number(unit)
 
 /// A boolean value.
 ///
-/// `true` or `false`
+/// `true` or `false`.
 @(impl = primitive)
 export type bool
 
@@ -132,7 +163,10 @@ export type string
 @(impl = primitive)
 export type tag
 
-/// A plane.
+/// An abstract plane.
+///
+/// A plane has a position and orientation in space defined by its origin and axes. A plane can be used
+/// to sketch on.
 @(impl = std_rust)
 export type Plane
 
@@ -180,7 +214,7 @@ export type Plane
 @(impl = std_rust)
 export type Sketch
 
-/// A solid is a collection of extrude surfaces.
+/// A solid is a collection of extruded surfaces.
 ///
 /// When you define a solid to a variable like:
 ///
@@ -226,15 +260,15 @@ export type Sketch
 @(impl = std_rust)
 export type Solid
 
-/// A face.
+/// A face of a solid.
 @(impl = std_rust)
 export type Face
 
-/// A helix.
+/// A helix; created by the `helix` function.
 @(impl = std_rust)
 export type Helix
 
-/// The edge of a solid.
+/// An edge of a solid.
 @(impl = std_rust)
 export type Edge
 
@@ -250,10 +284,10 @@ export type Point2d = [number(Length); 2]
 /// with type `Point3d`, use an array, e.g., `[0, 0, 0]` or `[5.0, 3.14, 6.8]`.
 export type Point3d = [number(Length); 3]
 
-/// An infinite line in 2d space.
+/// An abstract and infinite line in 2d space.
 @(impl = std_rust)
 export type Axis2d
 
-/// An infinite line in 3d space.
+/// An abstract and infinite line in 3d space.
 @(impl = std_rust)
 export type Axis3d

rust/kcl-lib/std/units.kcl

@@ -1,4 +1,11 @@
 /// Functions for converting numbers to different units.
+///
+/// All numbers in KCL include units, e.g., the number `42` is always '42 mm' or '42 degrees', etc.
+/// it is never just '42'. For more information, see [numeric types](/docs/kcl-lang/numeric).
+///
+/// Note that you only need to explicitly convert the units of a number if you need a specific unit
+/// for your own calculations. When calling a function, KCL will convert a number to the required
+/// units automatically (where possible, and give an error or warning if it's not possible).
 
 @no_std
 @settings(defaultLengthUnit = mm, kclVersion = 1.0)