From 0621e1a53e6b270b73e54580414d47d8b8e1c5ad Mon Sep 17 00:00:00 2001 From: Nick Cameron Date: Sun, 11 May 2025 19:32:33 +1200 Subject: [PATCH] Docs content (#6792) * Add documentation to modules, and some constants and types Signed-off-by: Nick Cameron * Improve the language reference Signed-off-by: Nick Cameron --------- Signed-off-by: Nick Cameron --- docs/kcl-lang/arithmetic.md | 53 +++++++ docs/kcl-lang/attributes.md | 30 ++++ docs/kcl-lang/functions.md | 46 +++++++ docs/kcl-lang/index.md | 18 ++- docs/kcl-lang/modules.md | 2 +- docs/kcl-lang/numeric.md | 46 +++++++ docs/kcl-lang/pipelines.md | 66 +++++++++ docs/kcl-lang/settings.md | 2 +- docs/kcl-lang/types.md | 130 +----------------- docs/kcl-std/consts/std-X.md | 4 +- docs/kcl-std/consts/std-XY.md | 4 +- docs/kcl-std/consts/std-XZ.md | 4 +- docs/kcl-std/consts/std-Y.md | 4 +- docs/kcl-std/consts/std-YZ.md | 4 +- docs/kcl-std/consts/std-Z.md | 4 +- docs/kcl-std/consts/std-turns-HALF_TURN.md | 4 +- docs/kcl-std/consts/std-turns-QUARTER_TURN.md | 4 +- .../consts/std-turns-THREE_QUARTER_TURN.md | 4 +- docs/kcl-std/consts/std-turns-ZERO.md | 4 +- docs/kcl-std/functions/std-helix.md | 2 +- docs/kcl-std/functions/std-math-abs.md | 4 +- docs/kcl-std/functions/std-math-acos.md | 4 +- docs/kcl-std/functions/std-math-asin.md | 4 +- docs/kcl-std/functions/std-math-atan.md | 4 +- docs/kcl-std/functions/std-math-atan2.md | 6 +- docs/kcl-std/functions/std-math-ceil.md | 4 +- docs/kcl-std/functions/std-math-cos.md | 4 +- docs/kcl-std/functions/std-math-floor.md | 4 +- docs/kcl-std/functions/std-math-ln.md | 4 +- docs/kcl-std/functions/std-math-log.md | 2 +- docs/kcl-std/functions/std-math-log10.md | 4 +- docs/kcl-std/functions/std-math-log2.md | 4 +- docs/kcl-std/functions/std-math-max.md | 2 +- docs/kcl-std/functions/std-math-min.md | 2 +- docs/kcl-std/functions/std-math-polar.md | 4 +- docs/kcl-std/functions/std-math-pow.md | 2 +- docs/kcl-std/functions/std-math-rem.md | 2 +- docs/kcl-std/functions/std-math-round.md | 4 +- docs/kcl-std/functions/std-math-sin.md | 4 +- docs/kcl-std/functions/std-math-sqrt.md | 4 +- docs/kcl-std/functions/std-math-tan.md | 4 +- docs/kcl-std/functions/std-offsetPlane.md | 2 +- docs/kcl-std/functions/std-sketch-revolve.md | 2 +- docs/kcl-std/functions/std-solid-chamfer.md | 2 +- docs/kcl-std/functions/std-solid-fillet.md | 2 +- docs/kcl-std/functions/std-solid-hollow.md | 2 +- .../functions/std-units-toCentimeters.md | 4 +- docs/kcl-std/functions/std-units-toDegrees.md | 4 +- docs/kcl-std/functions/std-units-toFeet.md | 4 +- docs/kcl-std/functions/std-units-toInches.md | 4 +- docs/kcl-std/functions/std-units-toMeters.md | 4 +- .../functions/std-units-toMillimeters.md | 4 +- docs/kcl-std/functions/std-units-toRadians.md | 4 +- docs/kcl-std/functions/std-units-toYards.md | 4 +- docs/kcl-std/lastSegX.md | 2 +- docs/kcl-std/lastSegY.md | 2 +- docs/kcl-std/legAngX.md | 2 +- docs/kcl-std/legAngY.md | 2 +- docs/kcl-std/legLen.md | 2 +- docs/kcl-std/loft.md | 2 +- docs/kcl-std/modules/std-array.md | 4 +- docs/kcl-std/modules/std-math.md | 4 +- docs/kcl-std/modules/std-sketch.md | 6 +- docs/kcl-std/modules/std-solid.md | 4 +- docs/kcl-std/modules/std-transform.md | 4 +- docs/kcl-std/modules/std-turns.md | 4 +- docs/kcl-std/modules/std-types.md | 6 +- docs/kcl-std/modules/std-units.md | 2 + docs/kcl-std/modules/std.md | 2 + docs/kcl-std/profileStartX.md | 2 +- docs/kcl-std/profileStartY.md | 2 +- docs/kcl-std/segAng.md | 2 +- docs/kcl-std/segEndX.md | 2 +- docs/kcl-std/segEndY.md | 2 +- docs/kcl-std/segLen.md | 2 +- docs/kcl-std/segStartX.md | 2 +- docs/kcl-std/segStartY.md | 2 +- docs/kcl-std/tangentToEnd.md | 2 +- docs/kcl-std/types/std-types-Axis2d.md | 4 +- docs/kcl-std/types/std-types-Axis3d.md | 4 +- docs/kcl-std/types/std-types-Edge.md | 4 +- docs/kcl-std/types/std-types-Face.md | 4 +- docs/kcl-std/types/std-types-Helix.md | 4 +- docs/kcl-std/types/std-types-Plane.md | 9 +- docs/kcl-std/types/std-types-Solid.md | 4 +- docs/kcl-std/types/std-types-any.md | 23 +++- docs/kcl-std/types/std-types-bool.md | 2 +- docs/kcl-std/types/std-types-number.md | 19 ++- rust/kcl-lib/std/array.kcl | 2 + rust/kcl-lib/std/math.kcl | 2 + rust/kcl-lib/std/prelude.kcl | 9 ++ rust/kcl-lib/std/sketch.kcl | 6 + rust/kcl-lib/std/solid.kcl | 3 + rust/kcl-lib/std/transform.kcl | 3 +- rust/kcl-lib/std/turns.kcl | 9 ++ rust/kcl-lib/std/types.kcl | 56 ++++++-- rust/kcl-lib/std/units.kcl | 7 + 97 files changed, 511 insertions(+), 282 deletions(-) create mode 100644 docs/kcl-lang/arithmetic.md create mode 100644 docs/kcl-lang/attributes.md create mode 100644 docs/kcl-lang/functions.md create mode 100644 docs/kcl-lang/numeric.md create mode 100644 docs/kcl-lang/pipelines.md diff --git a/docs/kcl-lang/arithmetic.md b/docs/kcl-lang/arithmetic.md new file mode 100644 index 000000000..d46d925af --- /dev/null +++ b/docs/kcl-lang/arithmetic.md @@ -0,0 +1,53 @@ +--- +title: "Arithmetic and logic" +excerpt: "Documentation of the KCL language for the Zoo Design Studio." +layout: manual +--- + +KCL supports the usual arithmetic operators on numbers and logic operators on booleans: + +| Operator | Meaning | +|----------|---------| +| `+` | Addition | +| `-` | Subtraction or unary negation | +| `*` | Multiplication | +| `/` | Division | +| `%` | Modulus aka remainder | +| `^` | Power, e.g., `x ^ 2` means `x` squared | +| `&` | Logical 'and' | +| `|` | Logical 'or' | +| `!` | Unary logical 'not' | + +KCL also supports comparsion operators which operate on numbers and produce booleans: + +| Operator | Meaning | +|----------|---------| +| `==` | Equal | +| `!=` | Not equal | +| `<` | Less than | +| `>` | Greater than | +| `<=` | Less than or equal | +| `>=` | Greater than or equal | + +Arithmetics and logic expressions can be arbitrairly combined with the usual rules of associativity and precedence, e.g., + +``` +myMathExpression = 3 + 1 * 2 / 3 - 7 +``` + +You can also nest expressions in parenthesis: + +``` +myMathExpression = 3 + (1 * 2 / (3 - 7)) +``` + +KCL numbers are implemented using [floating point numbers](https://en.wikipedia.org/wiki/Floating-point_arithmetic). This means that there are occasionally representation and rounding issues, and some oddities such as supporting positive and negative zero. + +Some operators can be applied to other types: + +- `+` can be used to concatenate strings, e.g., `'hello' + ' ' + 'world!'` +- Unary `-` can be used with planes or line-like objects such as axes to produce an object with opposite orientation, e.g., `-XY` is a plain which is aligned with `XY` but whose normal aligns with the negative Z axis. +- The following operators can be used with solids as shorthand for CSG operations: + - `+` or `|` for [`union`](/docs/kcl-std/union). + - `-` for [`subtract`](/docs/kcl-std/subtract). + - `&` for [`intersect`](/docs/kcl-std/intersect) diff --git a/docs/kcl-lang/attributes.md b/docs/kcl-lang/attributes.md new file mode 100644 index 000000000..2b28dd54e --- /dev/null +++ b/docs/kcl-lang/attributes.md @@ -0,0 +1,30 @@ +--- +title: "Attributes" +excerpt: "Documentation of the KCL language for the Zoo Design Studio." +layout: manual +--- + +Attributes are syntax which affects the language item they annotate. In KCL they are indicated using `@`. For example, `@settings` affects the file in which it appears. + +There are two kinds of attributes: named and unnamed attributes. Named attributes (e.g., `@settings`) have a name immediately after the `@` (e.g., `settings`) and affect their surrounding scope. Unnamed attributes have no name and affect the following item, e.g., + +```kcl,norun +@(lengthUnit = ft, coords = opengl) +import "tests/inputs/cube.obj" +``` + +has an unnamed attribute on the `import` statement. + +Named and unnamed attributes may take a parenthesized list of arguments (like a function). Named attributes may also appear without any arguments (e.g., `@no_std`). + +## Named attributes + +The `@settings` attribute affects the current file and accepts the following arguments: `defaultLengthUnit`, `defaultAngleUnit`, and `kclVersion`. See [settings](/docs/kcl-lang/settings) for details. + +The `@no_std` attribute affects the current file, takes no arguments, and causes the standard library to not be implicitly available. It can still be used by being explicitly imported. + +## Unnamed attributes + +Unnamed attributes may be used on `import` statements when importing non-KCL files. See [projects, modules, and imports](/docs/kcl-lang/modules) for details. + +Other unnamed attributes are used on functions inside the standard library, but these are not available in user code. diff --git a/docs/kcl-lang/functions.md b/docs/kcl-lang/functions.md new file mode 100644 index 000000000..a4fc32a84 --- /dev/null +++ b/docs/kcl-lang/functions.md @@ -0,0 +1,46 @@ +--- +title: "Functions" +excerpt: "Documentation of the KCL language for the Zoo Design Studio." +layout: manual +--- + +We have support for defining your own functions. Functions can take in any +type of argument. Below is an example of the syntax: + +``` +fn myFn(x) { + return x +} +``` + +As you can see above `myFn` just returns whatever it is given. + +KCL uses keyword arguments: + +``` +// If you declare a function like this +fn add(left, right) { + return left + right +} + +// You can call it like this: +total = add(left = 1, right = 2) +``` + +Functions can also declare one *unlabeled* arg. If you do want to declare an unlabeled arg, it must +be the first arg declared. + +``` +// The @ indicates an argument is used without a label. +// Note that only the first argument can use @. +fn increment(@x) { + return x + 1 +} + +fn add(@x, delta) { + return x + delta +} + +two = increment(1) +three = add(1, delta = 2) +``` diff --git a/docs/kcl-lang/index.md b/docs/kcl-lang/index.md index 4663979fa..db2ba51c8 100644 --- a/docs/kcl-lang/index.md +++ b/docs/kcl-lang/index.md @@ -1,12 +1,20 @@ --- -title: "KCL Language Guide" +title: "KCL Language Reference" excerpt: "Documentation of the KCL language for the Zoo Design Studio." layout: manual --- +This is a reference for KCL. If you are learning KCL, you may prefer the [guide]() which explains +things in a more tutorial fashion. + ## Topics -* [`Types`](/docs/kcl-lang/types) -* [`Modules`](/docs/kcl-lang/modules) -* [`Settings`](/docs/kcl-lang/settings) -* [`Known Issues`](/docs/kcl-lang/known-issues) +* [Pipelines](/docs/kcl-lang/pipelines) +* [Arithmetic and logic](/docs/kcl-lang/arithmetic) +* [Values and types](/docs/kcl-lang/types) +* [Numeric types and units](/docs/kcl-lang/numeric) +* [Functions](/docs/kcl-lang/functions) +* [Projects, modules, and imports](/docs/kcl-lang/modules) +* [Attributes](/docs/kcl-lang/attributes) +* [Settings](/docs/kcl-lang/settings) +* [Known Issues](/docs/kcl-lang/known-issues) diff --git a/docs/kcl-lang/modules.md b/docs/kcl-lang/modules.md index c88fc35d7..13b103940 100644 --- a/docs/kcl-lang/modules.md +++ b/docs/kcl-lang/modules.md @@ -1,6 +1,6 @@ --- title: "Modules" -excerpt: "Documentation of modules for the KCL language for the Zoo Design Studio." +excerpt: "Documentation of the KCL language for the Zoo Design Studio." layout: manual --- diff --git a/docs/kcl-lang/numeric.md b/docs/kcl-lang/numeric.md new file mode 100644 index 000000000..5e8650aa0 --- /dev/null +++ b/docs/kcl-lang/numeric.md @@ -0,0 +1,46 @@ +--- +title: "Numeric types and units" +excerpt: "Documentation of the KCL language for the Zoo Design Studio." +layout: manual +--- + +Numbers and numeric types in KCL include information about the units of the numbers. So rather than just having a number like `42`, we always have information about the units so we don't confuse 42 mm with 42 inches. + + +## Numeric literals + +When writing a number literal, you can use a unit suffix to explicitly state the unit, e.g., `42mm`. The following units are available: + +- Length units: + - metric: `mm`, `cm`, `m` + - imperial: `in`, `ft`, `yd` +- Angle units: `deg`, `rad` +- `_` to indicate a unitless number such as a count or ratio. + +If you write a numeric literal without a suffix, then the defaults for the current file are used. These defaults are specified using the `@settings` attribute, see [settings](/docs/kcl-lang/settings) for details. Note that if using the defaults, the KCL interpreter won't know whether you intend the number to be a length, angle, or count and will treat it as being possibly any of them. + + +## Numeric types + +Just like numbers carry units information, the `number` type also includes units information. Units are written in parentheses after the type, e.g., `number(mm)`. + +Any of the suffixes described above can be used meaning that values with that type have the supplied units. E.g., `number(mm)` is the type of number values with mm units and `number(_)` is the type of number values with no units. + +You can also use `number(Length)`, `number(Angle)`, or `number(Count)`. These types mean a number with any length, angle, or unitless (count) units, respectively (note that `number(_)` and `number(Count)` are equivalent since there is only one kind of unitless-ness). + + +## Function calls + +When calling a function with an argument with numeric type, the declared numeric type in the function signature and the units of the argument value used in the function call must be compatible. Units are adjusted automatically. For example, if a function requires an argument with type `number(mm)`, then you can call it with `2in` and the units will be automatically adjusted, but calling it with `90deg` will cause an error. + + +## Mixing units with arithmetic + +When doing arithmetic or comparisons, units will be adjusted as necessary if possible. However, often arithmetic expressions exceed the ability of KCL to accurately choose units which can result in warnings in your code or sometimes errors. In these cases, you will need to give KCL more information. Sometimes this can be done by making units explicit using suffixes. If not, then you will need to use *type ascription*, which asserts that an expression has the supplied type. For example, `(x * y): number(mm)` tells KCL that the units of `x * y` is mm. Note that type ascription does not do any adjustment of the numbers, e.g., `2mm: number(in)` has the value `2in` (note that this would be a very non-idiomatic way to use numeric type ascription, you could simply write `2in`. Usually type ascription is only necessary for supplying type information about the result of computation). + +KCL has no support for area, volume, or other higher dimension units. When internal unit tracking requires multiple dimensions, KCL essentially gives up. This is usually where the extra type information described above is needed. If doing computation with higher dimensioned units, you must ensure that all adjustments occur before any computation. E.g., if you want to compute an area with unknown units, you must convert all numbers to the same unit before starting. + + +## Explicit conversions + +You might sometimes need to convert from one unit to another for some calculation. You can do this implicitly when calling a function (see above), but if you can't or don't want to, then you can use the explicit conversion functions in the [`std::units`](/docs/kcl-std/modules/std-units) module. diff --git a/docs/kcl-lang/pipelines.md b/docs/kcl-lang/pipelines.md new file mode 100644 index 000000000..613337adc --- /dev/null +++ b/docs/kcl-lang/pipelines.md @@ -0,0 +1,66 @@ +--- +title: "Pipelines" +excerpt: "Documentation of the KCL language for the Zoo Design Studio." +layout: manual +--- + +It can be hard to read repeated function calls, because of all the nested brackets. + +```norun +i = 1 +x = h(g(f(i))) +``` + +You can make this easier to read by breaking it into many declarations, but that is a bit annoying. + +```norun +i = 1 +x0 = f(i) +x1 = g(x0) +x = h(x1) +``` + +Instead, you can use the pipeline operator (`|>`) to simplify this. + +Basically, `x |> f(%)` is a shorthand for `f(x)`. The left-hand side of the `|>` gets put into +the `%` in the right-hand side. + +So, this means `x |> f(%) |> g(%)` is shorthand for `g(f(x))`. The code example above, with its +somewhat-clunky `x0` and `x1` constants could be rewritten as + +```norun +i = 1 +x = i + |> f(%) + |> g(%) + |> h(%) +``` + +This helps keep your code neat and avoid unnecessary declarations. + +## Pipelines and keyword arguments + +Say you have a long pipeline of sketch functions, like this: + +```norun +startSketchOn(XZ) + |> line(%, end = [3, 4]) + |> line(%, end = [10, 10]) + |> line(%, end = [-13, -14]) + |> close(%) +``` + +In this example, each function call outputs a sketch, and it gets put into the next function call via +the `%`, into the first (unlabeled) argument. + +If a function call uses an unlabeled first parameter, it will default to `%` if it's not given. This +means that `|> line(%, end = [3, 4])` and `|> line(end = [3, 4])` are equivalent! So the above +could be rewritten as + +```norun +startSketchOn(XZ) + |> line(end = [3, 4]) + |> line(end = [10, 10]) + |> line(end = [-13, -14]) + |> close() +``` diff --git a/docs/kcl-lang/settings.md b/docs/kcl-lang/settings.md index f795cea8f..3d45418fd 100644 --- a/docs/kcl-lang/settings.md +++ b/docs/kcl-lang/settings.md @@ -1,6 +1,6 @@ --- title: "Settings" -excerpt: "Documentation of settings for the KCL language and Zoo Design Studio." +excerpt: "Documentation of the KCL language for the Zoo Design Studio." layout: manual --- diff --git a/docs/kcl-lang/types.md b/docs/kcl-lang/types.md index 39e26dcb6..51d77db6c 100644 --- a/docs/kcl-lang/types.md +++ b/docs/kcl-lang/types.md @@ -1,6 +1,6 @@ --- -title: "Types" -excerpt: "Documentation of types for the KCL standard library for the Zoo Design Studio." +title: "Values and types" +excerpt: "Documentation of the KCL language for the Zoo Design Studio." layout: manual --- @@ -52,131 +52,6 @@ their internal components. See the [modules and imports docs](modules) for more detail on importing geometry. -## Binary expressions - -You can also do math! Let's show an example below: - -``` -myMathExpression = 3 + 1 * 2 / 3 - 7 -``` - -You can nest expressions in parenthesis as well: - -``` -myMathExpression = 3 + (1 * 2 / (3 - 7)) -``` - -## Functions - -We also have support for defining your own functions. Functions can take in any -type of argument. Below is an example of the syntax: - -``` -fn myFn(x) { - return x -} -``` - -As you can see above `myFn` just returns whatever it is given. - -KCL's early drafts used positional arguments, but we now use keyword arguments: - -``` -// If you declare a function like this -fn add(left, right) { - return left + right -} - -// You can call it like this: -total = add(left = 1, right = 2) -``` - -Functions can also declare one *unlabeled* arg. If you do want to declare an unlabeled arg, it must -be the first arg declared. - -``` -// The @ indicates an argument can be used without a label. -// Note that only the first argument can use @. -fn increment(@x) { - return x + 1 -} - -fn add(@x, delta) { - return x + delta -} - -two = increment(1) -three = add(1, delta = 2) -``` - -## Pipelines - -It can be hard to read repeated function calls, because of all the nested brackets. - -```norun -i = 1 -x = h(g(f(i))) -``` - -You can make this easier to read by breaking it into many declarations, but that is a bit annoying. - -```norun -i = 1 -x0 = f(i) -x1 = g(x0) -x = h(x1) -``` - -Instead, you can use the pipeline operator (`|>`) to simplify this. - -Basically, `x |> f(%)` is a shorthand for `f(x)`. The left-hand side of the `|>` gets put into -the `%` in the right-hand side. - -So, this means `x |> f(%) |> g(%)` is shorthand for `g(f(x))`. The code example above, with its -somewhat-clunky `x0` and `x1` constants could be rewritten as - -```norun -i = 1 -x = i - |> f(%) - |> g(%) - |> h(%) -``` - -This helps keep your code neat and avoid unnecessary declarations. - -## Pipelines and keyword arguments - -Say you have a long pipeline of sketch functions, like this: - -```norun -startSketchOn(XZ) - |> line(%, end = [3, 4]) - |> line(%, end = [10, 10]) - |> line(%, end = [-13, -14]) - |> close(%) -``` - -In this example, each function call outputs a sketch, and it gets put into the next function call via -the `%`, into the first (unlabeled) argument. - -If a function call uses an unlabeled first parameter, it will default to `%` if it's not given. This -means that `|> line(%, end = [3, 4])` and `|> line(end = [3, 4])` are equivalent! So the above -could be rewritten as - -```norun -startSketchOn(XZ) - |> line(end = [3, 4]) - |> line(end = [10, 10]) - |> line(end = [-13, -14]) - |> close() -``` - -Note that we are still in the process of migrating KCL's standard library to use keyword arguments. So some -functions are still unfortunately using positional arguments. We're moving them over, so keep checking back. -Some functions are still using the old positional argument syntax. -Check the docs page for each function and look at its examples to see. - ## Tags Tags are used to give a name (tag) to a specific path. @@ -291,7 +166,6 @@ See how we use the tag `rectangleSegmentA001` in the `fillet` function outside the `rect` function. This is because the `rect` function is returning the sketch group that contains the tags. - --- If you find any issues using any of the above expressions or syntax, diff --git a/docs/kcl-std/consts/std-X.md b/docs/kcl-std/consts/std-X.md index 9e9bbcf32..9e87dd742 100644 --- a/docs/kcl-std/consts/std-X.md +++ b/docs/kcl-std/consts/std-X.md @@ -1,11 +1,11 @@ --- title: "X" subtitle: "Constant in std" -excerpt: "" +excerpt: "The X-axis (can be used in both 2d and 3d contexts)." layout: manual --- - +The X-axis (can be used in both 2d and 3d contexts). ```kcl X diff --git a/docs/kcl-std/consts/std-XY.md b/docs/kcl-std/consts/std-XY.md index 38959f864..7902f4b5d 100644 --- a/docs/kcl-std/consts/std-XY.md +++ b/docs/kcl-std/consts/std-XY.md @@ -1,11 +1,11 @@ --- title: "XY" subtitle: "Constant in std" -excerpt: "" +excerpt: "An abstract 3d plane aligned with the X and Y axes. Its normal is the positive Z axis." layout: manual --- - +An abstract 3d plane aligned with the X and Y axes. Its normal is the positive Z axis. ```kcl XY diff --git a/docs/kcl-std/consts/std-XZ.md b/docs/kcl-std/consts/std-XZ.md index 91ae5b2d2..b61e49f7a 100644 --- a/docs/kcl-std/consts/std-XZ.md +++ b/docs/kcl-std/consts/std-XZ.md @@ -1,11 +1,11 @@ --- title: "XZ" subtitle: "Constant in std" -excerpt: "" +excerpt: "An abstract 3d plane aligned with the X and Z axes. Its normal is the negative Y axis." layout: manual --- - +An abstract 3d plane aligned with the X and Z axes. Its normal is the negative Y axis. ```kcl XZ diff --git a/docs/kcl-std/consts/std-Y.md b/docs/kcl-std/consts/std-Y.md index e71dbf7f4..69c5377d1 100644 --- a/docs/kcl-std/consts/std-Y.md +++ b/docs/kcl-std/consts/std-Y.md @@ -1,11 +1,11 @@ --- title: "Y" subtitle: "Constant in std" -excerpt: "" +excerpt: "The Y-axis (can be used in both 2d and 3d contexts)." layout: manual --- - +The Y-axis (can be used in both 2d and 3d contexts). ```kcl Y diff --git a/docs/kcl-std/consts/std-YZ.md b/docs/kcl-std/consts/std-YZ.md index 3bc34f5fd..afe554f7a 100644 --- a/docs/kcl-std/consts/std-YZ.md +++ b/docs/kcl-std/consts/std-YZ.md @@ -1,11 +1,11 @@ --- title: "YZ" subtitle: "Constant in std" -excerpt: "" +excerpt: "An abstract 3d plane aligned with the Y and Z axes. Its normal is the positive X axis." layout: manual --- - +An abstract 3d plane aligned with the Y and Z axes. Its normal is the positive X axis. ```kcl YZ diff --git a/docs/kcl-std/consts/std-Z.md b/docs/kcl-std/consts/std-Z.md index ab7394405..9620d3a4a 100644 --- a/docs/kcl-std/consts/std-Z.md +++ b/docs/kcl-std/consts/std-Z.md @@ -1,11 +1,11 @@ --- title: "Z" subtitle: "Constant in std" -excerpt: "" +excerpt: "The 3D Z-axis." layout: manual --- - +The 3D Z-axis. ```kcl Z diff --git a/docs/kcl-std/consts/std-turns-HALF_TURN.md b/docs/kcl-std/consts/std-turns-HALF_TURN.md index b449f7f2e..7deae079c 100644 --- a/docs/kcl-std/consts/std-turns-HALF_TURN.md +++ b/docs/kcl-std/consts/std-turns-HALF_TURN.md @@ -1,11 +1,11 @@ --- title: "turns::HALF_TURN" subtitle: "Constant in std::turns" -excerpt: "" +excerpt: "A half turn, 180 degrees or π radians." layout: manual --- - +A half turn, 180 degrees or π radians. ```kcl turns::HALF_TURN: number(deg) = 180deg diff --git a/docs/kcl-std/consts/std-turns-QUARTER_TURN.md b/docs/kcl-std/consts/std-turns-QUARTER_TURN.md index 6c2e181e6..3f728aac3 100644 --- a/docs/kcl-std/consts/std-turns-QUARTER_TURN.md +++ b/docs/kcl-std/consts/std-turns-QUARTER_TURN.md @@ -1,11 +1,11 @@ --- title: "turns::QUARTER_TURN" subtitle: "Constant in std::turns" -excerpt: "" +excerpt: "A quarter turn, 90 degrees or π/2 radians." layout: manual --- - +A quarter turn, 90 degrees or π/2 radians. ```kcl turns::QUARTER_TURN: number(deg) = 90deg diff --git a/docs/kcl-std/consts/std-turns-THREE_QUARTER_TURN.md b/docs/kcl-std/consts/std-turns-THREE_QUARTER_TURN.md index bf64fa27e..f8404bcf7 100644 --- a/docs/kcl-std/consts/std-turns-THREE_QUARTER_TURN.md +++ b/docs/kcl-std/consts/std-turns-THREE_QUARTER_TURN.md @@ -1,11 +1,11 @@ --- title: "turns::THREE_QUARTER_TURN" subtitle: "Constant in std::turns" -excerpt: "" +excerpt: "Three quarters of a turn, 270 degrees or 1.5*π radians." layout: manual --- - +Three quarters of a turn, 270 degrees or 1.5*π radians. ```kcl turns::THREE_QUARTER_TURN: number(deg) = 270deg diff --git a/docs/kcl-std/consts/std-turns-ZERO.md b/docs/kcl-std/consts/std-turns-ZERO.md index 95d4b9f90..7ed8e19e7 100644 --- a/docs/kcl-std/consts/std-turns-ZERO.md +++ b/docs/kcl-std/consts/std-turns-ZERO.md @@ -1,11 +1,11 @@ --- title: "turns::ZERO" subtitle: "Constant in std::turns" -excerpt: "" +excerpt: "No turn, zero degrees/radians." layout: manual --- - +No turn, zero degrees/radians. ```kcl turns::ZERO: number = 0 diff --git a/docs/kcl-std/functions/std-helix.md b/docs/kcl-std/functions/std-helix.md index ec5b8bbca..d00d2ae37 100644 --- a/docs/kcl-std/functions/std-helix.md +++ b/docs/kcl-std/functions/std-helix.md @@ -35,7 +35,7 @@ helix( ### Returns -[`Helix`](/docs/kcl-std/types/std-types-Helix) - A helix. +[`Helix`](/docs/kcl-std/types/std-types-Helix) - A helix; created by the `helix` function. ### Examples diff --git a/docs/kcl-std/functions/std-math-abs.md b/docs/kcl-std/functions/std-math-abs.md index ba175793f..bfe6f451e 100644 --- a/docs/kcl-std/functions/std-math-abs.md +++ b/docs/kcl-std/functions/std-math-abs.md @@ -17,11 +17,11 @@ abs(@input: number): number | Name | Type | Description | Required | |----------|------|-------------|----------| -| `input` | [`number`](/docs/kcl-std/types/std-types-number) | A number | Yes | +| `input` | [`number`](/docs/kcl-std/types/std-types-number) | A number. | Yes | ### Returns -[`number`](/docs/kcl-std/types/std-types-number) - A number +[`number`](/docs/kcl-std/types/std-types-number) - A number. ### Examples diff --git a/docs/kcl-std/functions/std-math-acos.md b/docs/kcl-std/functions/std-math-acos.md index e3aaefa9a..b43a823d6 100644 --- a/docs/kcl-std/functions/std-math-acos.md +++ b/docs/kcl-std/functions/std-math-acos.md @@ -17,11 +17,11 @@ acos(@num: number(_)): number(rad) | Name | Type | Description | Required | |----------|------|-------------|----------| -| `num` | [`number(_)`](/docs/kcl-std/types/std-types-number) | A number | Yes | +| `num` | [`number(_)`](/docs/kcl-std/types/std-types-number) | A number. | Yes | ### Returns -[`number(rad)`](/docs/kcl-std/types/std-types-number) - A number +[`number(rad)`](/docs/kcl-std/types/std-types-number) - A number. ### Examples diff --git a/docs/kcl-std/functions/std-math-asin.md b/docs/kcl-std/functions/std-math-asin.md index 7f1e78b35..8551a3a69 100644 --- a/docs/kcl-std/functions/std-math-asin.md +++ b/docs/kcl-std/functions/std-math-asin.md @@ -17,11 +17,11 @@ asin(@num: number(_)): number(rad) | Name | Type | Description | Required | |----------|------|-------------|----------| -| `num` | [`number(_)`](/docs/kcl-std/types/std-types-number) | A number | Yes | +| `num` | [`number(_)`](/docs/kcl-std/types/std-types-number) | A number. | Yes | ### Returns -[`number(rad)`](/docs/kcl-std/types/std-types-number) - A number +[`number(rad)`](/docs/kcl-std/types/std-types-number) - A number. ### Examples diff --git a/docs/kcl-std/functions/std-math-atan.md b/docs/kcl-std/functions/std-math-atan.md index f45563648..e54a59d3d 100644 --- a/docs/kcl-std/functions/std-math-atan.md +++ b/docs/kcl-std/functions/std-math-atan.md @@ -17,11 +17,11 @@ Consider using `atan2()` instead for the true inverse of tangent. | Name | Type | Description | Required | |----------|------|-------------|----------| -| `num` | [`number(_)`](/docs/kcl-std/types/std-types-number) | A number | Yes | +| `num` | [`number(_)`](/docs/kcl-std/types/std-types-number) | A number. | Yes | ### Returns -[`number(rad)`](/docs/kcl-std/types/std-types-number) - A number +[`number(rad)`](/docs/kcl-std/types/std-types-number) - A number. ### Examples diff --git a/docs/kcl-std/functions/std-math-atan2.md b/docs/kcl-std/functions/std-math-atan2.md index e4b1285c0..e58d09361 100644 --- a/docs/kcl-std/functions/std-math-atan2.md +++ b/docs/kcl-std/functions/std-math-atan2.md @@ -20,12 +20,12 @@ atan2( | Name | Type | Description | Required | |----------|------|-------------|----------| -| `y` | [`number(Length)`](/docs/kcl-std/types/std-types-number) | A number | Yes | -| `x` | [`number(Length)`](/docs/kcl-std/types/std-types-number) | A number | Yes | +| `y` | [`number(Length)`](/docs/kcl-std/types/std-types-number) | A number. | Yes | +| `x` | [`number(Length)`](/docs/kcl-std/types/std-types-number) | A number. | Yes | ### Returns -[`number(rad)`](/docs/kcl-std/types/std-types-number) - A number +[`number(rad)`](/docs/kcl-std/types/std-types-number) - A number. ### Examples diff --git a/docs/kcl-std/functions/std-math-ceil.md b/docs/kcl-std/functions/std-math-ceil.md index 15a726cdf..09fbbb9e5 100644 --- a/docs/kcl-std/functions/std-math-ceil.md +++ b/docs/kcl-std/functions/std-math-ceil.md @@ -17,11 +17,11 @@ ceil(@input: number): number | Name | Type | Description | Required | |----------|------|-------------|----------| -| `input` | [`number`](/docs/kcl-std/types/std-types-number) | A number | Yes | +| `input` | [`number`](/docs/kcl-std/types/std-types-number) | A number. | Yes | ### Returns -[`number`](/docs/kcl-std/types/std-types-number) - A number +[`number`](/docs/kcl-std/types/std-types-number) - A number. ### Examples diff --git a/docs/kcl-std/functions/std-math-cos.md b/docs/kcl-std/functions/std-math-cos.md index 007ee639b..c3836bcae 100644 --- a/docs/kcl-std/functions/std-math-cos.md +++ b/docs/kcl-std/functions/std-math-cos.md @@ -17,11 +17,11 @@ cos(@num: number(Angle)): number(_) | Name | Type | Description | Required | |----------|------|-------------|----------| -| `num` | [`number(Angle)`](/docs/kcl-std/types/std-types-number) | A number | Yes | +| `num` | [`number(Angle)`](/docs/kcl-std/types/std-types-number) | A number. | Yes | ### Returns -[`number(_)`](/docs/kcl-std/types/std-types-number) - A number +[`number(_)`](/docs/kcl-std/types/std-types-number) - A number. ### Examples diff --git a/docs/kcl-std/functions/std-math-floor.md b/docs/kcl-std/functions/std-math-floor.md index 72d146458..34e9a3037 100644 --- a/docs/kcl-std/functions/std-math-floor.md +++ b/docs/kcl-std/functions/std-math-floor.md @@ -17,11 +17,11 @@ floor(@input: number): number | Name | Type | Description | Required | |----------|------|-------------|----------| -| `input` | [`number`](/docs/kcl-std/types/std-types-number) | A number | Yes | +| `input` | [`number`](/docs/kcl-std/types/std-types-number) | A number. | Yes | ### Returns -[`number`](/docs/kcl-std/types/std-types-number) - A number +[`number`](/docs/kcl-std/types/std-types-number) - A number. ### Examples diff --git a/docs/kcl-std/functions/std-math-ln.md b/docs/kcl-std/functions/std-math-ln.md index 5d0756832..bbf83be4c 100644 --- a/docs/kcl-std/functions/std-math-ln.md +++ b/docs/kcl-std/functions/std-math-ln.md @@ -17,11 +17,11 @@ ln(@input: number): number | Name | Type | Description | Required | |----------|------|-------------|----------| -| `input` | [`number`](/docs/kcl-std/types/std-types-number) | A number | Yes | +| `input` | [`number`](/docs/kcl-std/types/std-types-number) | A number. | Yes | ### Returns -[`number`](/docs/kcl-std/types/std-types-number) - A number +[`number`](/docs/kcl-std/types/std-types-number) - A number. ### Examples diff --git a/docs/kcl-std/functions/std-math-log.md b/docs/kcl-std/functions/std-math-log.md index 693a69ebc..0fd94e2e6 100644 --- a/docs/kcl-std/functions/std-math-log.md +++ b/docs/kcl-std/functions/std-math-log.md @@ -27,7 +27,7 @@ and `log10` can produce more accurate results for base 10. ### Returns -[`number`](/docs/kcl-std/types/std-types-number) - A number +[`number`](/docs/kcl-std/types/std-types-number) - A number. ### Examples diff --git a/docs/kcl-std/functions/std-math-log10.md b/docs/kcl-std/functions/std-math-log10.md index 58e3fea9c..74b3fb4c4 100644 --- a/docs/kcl-std/functions/std-math-log10.md +++ b/docs/kcl-std/functions/std-math-log10.md @@ -17,11 +17,11 @@ log10(@input: number): number | Name | Type | Description | Required | |----------|------|-------------|----------| -| `input` | [`number`](/docs/kcl-std/types/std-types-number) | A number | Yes | +| `input` | [`number`](/docs/kcl-std/types/std-types-number) | A number. | Yes | ### Returns -[`number`](/docs/kcl-std/types/std-types-number) - A number +[`number`](/docs/kcl-std/types/std-types-number) - A number. ### Examples diff --git a/docs/kcl-std/functions/std-math-log2.md b/docs/kcl-std/functions/std-math-log2.md index 5b8686d8c..175af8d62 100644 --- a/docs/kcl-std/functions/std-math-log2.md +++ b/docs/kcl-std/functions/std-math-log2.md @@ -17,11 +17,11 @@ log2(@input: number): number | Name | Type | Description | Required | |----------|------|-------------|----------| -| `input` | [`number`](/docs/kcl-std/types/std-types-number) | A number | Yes | +| `input` | [`number`](/docs/kcl-std/types/std-types-number) | A number. | Yes | ### Returns -[`number`](/docs/kcl-std/types/std-types-number) - A number +[`number`](/docs/kcl-std/types/std-types-number) - A number. ### Examples diff --git a/docs/kcl-std/functions/std-math-max.md b/docs/kcl-std/functions/std-math-max.md index 2d6d1280a..a7a666018 100644 --- a/docs/kcl-std/functions/std-math-max.md +++ b/docs/kcl-std/functions/std-math-max.md @@ -21,7 +21,7 @@ max(@input: [number; 1+]): number ### Returns -[`number`](/docs/kcl-std/types/std-types-number) - A number +[`number`](/docs/kcl-std/types/std-types-number) - A number. ### Examples diff --git a/docs/kcl-std/functions/std-math-min.md b/docs/kcl-std/functions/std-math-min.md index 47f235e95..d80e31f6c 100644 --- a/docs/kcl-std/functions/std-math-min.md +++ b/docs/kcl-std/functions/std-math-min.md @@ -21,7 +21,7 @@ min(@input: [number; 1+]): number ### Returns -[`number`](/docs/kcl-std/types/std-types-number) - A number +[`number`](/docs/kcl-std/types/std-types-number) - A number. ### Examples diff --git a/docs/kcl-std/functions/std-math-polar.md b/docs/kcl-std/functions/std-math-polar.md index 37bd1b085..6fe41824f 100644 --- a/docs/kcl-std/functions/std-math-polar.md +++ b/docs/kcl-std/functions/std-math-polar.md @@ -21,8 +21,8 @@ cartesian (x/y/z grid) coordinates. | Name | Type | Description | Required | |----------|------|-------------|----------| -| `angle` | [`number(rad)`](/docs/kcl-std/types/std-types-number) | A number | Yes | -| `length` | [`number(Length)`](/docs/kcl-std/types/std-types-number) | A number | Yes | +| `angle` | [`number(rad)`](/docs/kcl-std/types/std-types-number) | A number. | Yes | +| `length` | [`number(Length)`](/docs/kcl-std/types/std-types-number) | A number. | Yes | ### Returns diff --git a/docs/kcl-std/functions/std-math-pow.md b/docs/kcl-std/functions/std-math-pow.md index 6b180f071..ec51260aa 100644 --- a/docs/kcl-std/functions/std-math-pow.md +++ b/docs/kcl-std/functions/std-math-pow.md @@ -25,7 +25,7 @@ pow( ### Returns -[`number`](/docs/kcl-std/types/std-types-number) - A number +[`number`](/docs/kcl-std/types/std-types-number) - A number. ### Examples diff --git a/docs/kcl-std/functions/std-math-rem.md b/docs/kcl-std/functions/std-math-rem.md index d80d92664..6b84c1ccc 100644 --- a/docs/kcl-std/functions/std-math-rem.md +++ b/docs/kcl-std/functions/std-math-rem.md @@ -26,7 +26,7 @@ If `num` is negative, the result will be too. ### Returns -[`number`](/docs/kcl-std/types/std-types-number) - A number +[`number`](/docs/kcl-std/types/std-types-number) - A number. ### Examples diff --git a/docs/kcl-std/functions/std-math-round.md b/docs/kcl-std/functions/std-math-round.md index 2ef19b28f..438553047 100644 --- a/docs/kcl-std/functions/std-math-round.md +++ b/docs/kcl-std/functions/std-math-round.md @@ -17,11 +17,11 @@ round(@input: number): number | Name | Type | Description | Required | |----------|------|-------------|----------| -| `input` | [`number`](/docs/kcl-std/types/std-types-number) | A number | Yes | +| `input` | [`number`](/docs/kcl-std/types/std-types-number) | A number. | Yes | ### Returns -[`number`](/docs/kcl-std/types/std-types-number) - A number +[`number`](/docs/kcl-std/types/std-types-number) - A number. ### Examples diff --git a/docs/kcl-std/functions/std-math-sin.md b/docs/kcl-std/functions/std-math-sin.md index fd95c2cf4..0e03f7ecd 100644 --- a/docs/kcl-std/functions/std-math-sin.md +++ b/docs/kcl-std/functions/std-math-sin.md @@ -17,11 +17,11 @@ sin(@num: number(Angle)): number(_) | Name | Type | Description | Required | |----------|------|-------------|----------| -| `num` | [`number(Angle)`](/docs/kcl-std/types/std-types-number) | A number | Yes | +| `num` | [`number(Angle)`](/docs/kcl-std/types/std-types-number) | A number. | Yes | ### Returns -[`number(_)`](/docs/kcl-std/types/std-types-number) - A number +[`number(_)`](/docs/kcl-std/types/std-types-number) - A number. ### Examples diff --git a/docs/kcl-std/functions/std-math-sqrt.md b/docs/kcl-std/functions/std-math-sqrt.md index 25370c9a6..ee568cb19 100644 --- a/docs/kcl-std/functions/std-math-sqrt.md +++ b/docs/kcl-std/functions/std-math-sqrt.md @@ -17,11 +17,11 @@ sqrt(@input: number): number | Name | Type | Description | Required | |----------|------|-------------|----------| -| `input` | [`number`](/docs/kcl-std/types/std-types-number) | A number | Yes | +| `input` | [`number`](/docs/kcl-std/types/std-types-number) | A number. | Yes | ### Returns -[`number`](/docs/kcl-std/types/std-types-number) - A number +[`number`](/docs/kcl-std/types/std-types-number) - A number. ### Examples diff --git a/docs/kcl-std/functions/std-math-tan.md b/docs/kcl-std/functions/std-math-tan.md index 37ed657bd..7dde5791c 100644 --- a/docs/kcl-std/functions/std-math-tan.md +++ b/docs/kcl-std/functions/std-math-tan.md @@ -17,11 +17,11 @@ tan(@num: number(Angle)): number(_) | Name | Type | Description | Required | |----------|------|-------------|----------| -| `num` | [`number(Angle)`](/docs/kcl-std/types/std-types-number) | A number | Yes | +| `num` | [`number(Angle)`](/docs/kcl-std/types/std-types-number) | A number. | Yes | ### Returns -[`number(_)`](/docs/kcl-std/types/std-types-number) - A number +[`number(_)`](/docs/kcl-std/types/std-types-number) - A number. ### Examples diff --git a/docs/kcl-std/functions/std-offsetPlane.md b/docs/kcl-std/functions/std-offsetPlane.md index 0529306d8..ba344c028 100644 --- a/docs/kcl-std/functions/std-offsetPlane.md +++ b/docs/kcl-std/functions/std-offsetPlane.md @@ -26,7 +26,7 @@ plane and 10 units away from it. ### Returns -[`Plane`](/docs/kcl-std/types/std-types-Plane) - A plane. +[`Plane`](/docs/kcl-std/types/std-types-Plane) - An abstract plane. ### Examples diff --git a/docs/kcl-std/functions/std-sketch-revolve.md b/docs/kcl-std/functions/std-sketch-revolve.md index 28d06b95c..c84dbbc5e 100644 --- a/docs/kcl-std/functions/std-sketch-revolve.md +++ b/docs/kcl-std/functions/std-sketch-revolve.md @@ -46,7 +46,7 @@ revolved around the same axis. ### Returns -[`Solid`](/docs/kcl-std/types/std-types-Solid) - A solid is a collection of extrude surfaces. +[`Solid`](/docs/kcl-std/types/std-types-Solid) - A solid is a collection of extruded surfaces. ### Examples diff --git a/docs/kcl-std/functions/std-solid-chamfer.md b/docs/kcl-std/functions/std-solid-chamfer.md index f0a5ab896..d26066eef 100644 --- a/docs/kcl-std/functions/std-solid-chamfer.md +++ b/docs/kcl-std/functions/std-solid-chamfer.md @@ -31,7 +31,7 @@ a sharp, straight transitional edge. ### Returns -[`Solid`](/docs/kcl-std/types/std-types-Solid) - A solid is a collection of extrude surfaces. +[`Solid`](/docs/kcl-std/types/std-types-Solid) - A solid is a collection of extruded surfaces. ### Examples diff --git a/docs/kcl-std/functions/std-solid-fillet.md b/docs/kcl-std/functions/std-solid-fillet.md index e6fd4c297..4b0f168cf 100644 --- a/docs/kcl-std/functions/std-solid-fillet.md +++ b/docs/kcl-std/functions/std-solid-fillet.md @@ -33,7 +33,7 @@ will smoothly blend the transition. ### Returns -[`Solid`](/docs/kcl-std/types/std-types-Solid) - A solid is a collection of extrude surfaces. +[`Solid`](/docs/kcl-std/types/std-types-Solid) - A solid is a collection of extruded surfaces. ### Examples diff --git a/docs/kcl-std/functions/std-solid-hollow.md b/docs/kcl-std/functions/std-solid-hollow.md index fc7c2f5a1..70c204482 100644 --- a/docs/kcl-std/functions/std-solid-hollow.md +++ b/docs/kcl-std/functions/std-solid-hollow.md @@ -26,7 +26,7 @@ provided thickness remains around the exterior of the shape. ### Returns -[`Solid`](/docs/kcl-std/types/std-types-Solid) - A solid is a collection of extrude surfaces. +[`Solid`](/docs/kcl-std/types/std-types-Solid) - A solid is a collection of extruded surfaces. ### Examples diff --git a/docs/kcl-std/functions/std-units-toCentimeters.md b/docs/kcl-std/functions/std-units-toCentimeters.md index 3f911733b..308558486 100644 --- a/docs/kcl-std/functions/std-units-toCentimeters.md +++ b/docs/kcl-std/functions/std-units-toCentimeters.md @@ -17,11 +17,11 @@ units::toCentimeters(@num: number(cm)): number(cm) | Name | Type | Description | Required | |----------|------|-------------|----------| -| `num` | [`number(cm)`](/docs/kcl-std/types/std-types-number) | A number | Yes | +| `num` | [`number(cm)`](/docs/kcl-std/types/std-types-number) | A number. | Yes | ### Returns -[`number(cm)`](/docs/kcl-std/types/std-types-number) - A number +[`number(cm)`](/docs/kcl-std/types/std-types-number) - A number. diff --git a/docs/kcl-std/functions/std-units-toDegrees.md b/docs/kcl-std/functions/std-units-toDegrees.md index 238d3bb21..ea2194c08 100644 --- a/docs/kcl-std/functions/std-units-toDegrees.md +++ b/docs/kcl-std/functions/std-units-toDegrees.md @@ -17,11 +17,11 @@ units::toDegrees(@num: number(deg)): number(deg) | Name | Type | Description | Required | |----------|------|-------------|----------| -| `num` | [`number(deg)`](/docs/kcl-std/types/std-types-number) | A number | Yes | +| `num` | [`number(deg)`](/docs/kcl-std/types/std-types-number) | A number. | Yes | ### Returns -[`number(deg)`](/docs/kcl-std/types/std-types-number) - A number +[`number(deg)`](/docs/kcl-std/types/std-types-number) - A number. ### Examples diff --git a/docs/kcl-std/functions/std-units-toFeet.md b/docs/kcl-std/functions/std-units-toFeet.md index 5998f846c..490c8aaa6 100644 --- a/docs/kcl-std/functions/std-units-toFeet.md +++ b/docs/kcl-std/functions/std-units-toFeet.md @@ -17,11 +17,11 @@ units::toFeet(@num: number(ft)): number(ft) | Name | Type | Description | Required | |----------|------|-------------|----------| -| `num` | [`number(ft)`](/docs/kcl-std/types/std-types-number) | A number | Yes | +| `num` | [`number(ft)`](/docs/kcl-std/types/std-types-number) | A number. | Yes | ### Returns -[`number(ft)`](/docs/kcl-std/types/std-types-number) - A number +[`number(ft)`](/docs/kcl-std/types/std-types-number) - A number. diff --git a/docs/kcl-std/functions/std-units-toInches.md b/docs/kcl-std/functions/std-units-toInches.md index 09ddae7d6..f28540fee 100644 --- a/docs/kcl-std/functions/std-units-toInches.md +++ b/docs/kcl-std/functions/std-units-toInches.md @@ -17,11 +17,11 @@ units::toInches(@num: number(in)): number(in) | Name | Type | Description | Required | |----------|------|-------------|----------| -| `num` | [`number(in)`](/docs/kcl-std/types/std-types-number) | A number | Yes | +| `num` | [`number(in)`](/docs/kcl-std/types/std-types-number) | A number. | Yes | ### Returns -[`number(in)`](/docs/kcl-std/types/std-types-number) - A number +[`number(in)`](/docs/kcl-std/types/std-types-number) - A number. diff --git a/docs/kcl-std/functions/std-units-toMeters.md b/docs/kcl-std/functions/std-units-toMeters.md index 014227fd3..725352154 100644 --- a/docs/kcl-std/functions/std-units-toMeters.md +++ b/docs/kcl-std/functions/std-units-toMeters.md @@ -17,11 +17,11 @@ units::toMeters(@num: number(m)): number(m) | Name | Type | Description | Required | |----------|------|-------------|----------| -| `num` | [`number(m)`](/docs/kcl-std/types/std-types-number) | A number | Yes | +| `num` | [`number(m)`](/docs/kcl-std/types/std-types-number) | A number. | Yes | ### Returns -[`number(m)`](/docs/kcl-std/types/std-types-number) - A number +[`number(m)`](/docs/kcl-std/types/std-types-number) - A number. diff --git a/docs/kcl-std/functions/std-units-toMillimeters.md b/docs/kcl-std/functions/std-units-toMillimeters.md index 1ce611c14..17e0f552f 100644 --- a/docs/kcl-std/functions/std-units-toMillimeters.md +++ b/docs/kcl-std/functions/std-units-toMillimeters.md @@ -17,11 +17,11 @@ units::toMillimeters(@num: number(mm)): number(mm) | Name | Type | Description | Required | |----------|------|-------------|----------| -| `num` | [`number(mm)`](/docs/kcl-std/types/std-types-number) | A number | Yes | +| `num` | [`number(mm)`](/docs/kcl-std/types/std-types-number) | A number. | Yes | ### Returns -[`number(mm)`](/docs/kcl-std/types/std-types-number) - A number +[`number(mm)`](/docs/kcl-std/types/std-types-number) - A number. diff --git a/docs/kcl-std/functions/std-units-toRadians.md b/docs/kcl-std/functions/std-units-toRadians.md index c850f2f69..e052f8509 100644 --- a/docs/kcl-std/functions/std-units-toRadians.md +++ b/docs/kcl-std/functions/std-units-toRadians.md @@ -17,11 +17,11 @@ units::toRadians(@num: number(rad)): number(rad) | Name | Type | Description | Required | |----------|------|-------------|----------| -| `num` | [`number(rad)`](/docs/kcl-std/types/std-types-number) | A number | Yes | +| `num` | [`number(rad)`](/docs/kcl-std/types/std-types-number) | A number. | Yes | ### Returns -[`number(rad)`](/docs/kcl-std/types/std-types-number) - A number +[`number(rad)`](/docs/kcl-std/types/std-types-number) - A number. ### Examples diff --git a/docs/kcl-std/functions/std-units-toYards.md b/docs/kcl-std/functions/std-units-toYards.md index 927721dd3..28fc7ce06 100644 --- a/docs/kcl-std/functions/std-units-toYards.md +++ b/docs/kcl-std/functions/std-units-toYards.md @@ -17,11 +17,11 @@ units::toYards(@num: number(yd)): number(yd) | Name | Type | Description | Required | |----------|------|-------------|----------| -| `num` | [`number(yd)`](/docs/kcl-std/types/std-types-number) | A number | Yes | +| `num` | [`number(yd)`](/docs/kcl-std/types/std-types-number) | A number. | Yes | ### Returns -[`number(yd)`](/docs/kcl-std/types/std-types-number) - A number +[`number(yd)`](/docs/kcl-std/types/std-types-number) - A number. diff --git a/docs/kcl-std/lastSegX.md b/docs/kcl-std/lastSegX.md index 0cffb28e8..b692aeded 100644 --- a/docs/kcl-std/lastSegX.md +++ b/docs/kcl-std/lastSegX.md @@ -21,7 +21,7 @@ lastSegX(@sketch: Sketch): number ### Returns -[`number`](/docs/kcl-std/types/std-types-number) - A number +[`number`](/docs/kcl-std/types/std-types-number) - A number. ### Examples diff --git a/docs/kcl-std/lastSegY.md b/docs/kcl-std/lastSegY.md index 2ee0297ed..c7331fb72 100644 --- a/docs/kcl-std/lastSegY.md +++ b/docs/kcl-std/lastSegY.md @@ -21,7 +21,7 @@ lastSegY(@sketch: Sketch): number ### Returns -[`number`](/docs/kcl-std/types/std-types-number) - A number +[`number`](/docs/kcl-std/types/std-types-number) - A number. ### Examples diff --git a/docs/kcl-std/legAngX.md b/docs/kcl-std/legAngX.md index 3b84189e4..c5b5bce5b 100644 --- a/docs/kcl-std/legAngX.md +++ b/docs/kcl-std/legAngX.md @@ -25,7 +25,7 @@ legAngX( ### Returns -[`number`](/docs/kcl-std/types/std-types-number) - A number +[`number`](/docs/kcl-std/types/std-types-number) - A number. ### Examples diff --git a/docs/kcl-std/legAngY.md b/docs/kcl-std/legAngY.md index 659b7f1ac..f05e1a030 100644 --- a/docs/kcl-std/legAngY.md +++ b/docs/kcl-std/legAngY.md @@ -25,7 +25,7 @@ legAngY( ### Returns -[`number`](/docs/kcl-std/types/std-types-number) - A number +[`number`](/docs/kcl-std/types/std-types-number) - A number. ### Examples diff --git a/docs/kcl-std/legLen.md b/docs/kcl-std/legLen.md index 6a5a4ba60..6e6234eef 100644 --- a/docs/kcl-std/legLen.md +++ b/docs/kcl-std/legLen.md @@ -25,7 +25,7 @@ legLen( ### Returns -[`number`](/docs/kcl-std/types/std-types-number) - A number +[`number`](/docs/kcl-std/types/std-types-number) - A number. ### Examples diff --git a/docs/kcl-std/loft.md b/docs/kcl-std/loft.md index dcded136e..1731833d0 100644 --- a/docs/kcl-std/loft.md +++ b/docs/kcl-std/loft.md @@ -35,7 +35,7 @@ The sketches need to closed and on the same plane. ### Returns -[`Solid`](/docs/kcl-std/types/std-types-Solid) - A solid is a collection of extrude surfaces. +[`Solid`](/docs/kcl-std/types/std-types-Solid) - A solid is a collection of extruded surfaces. ### Examples diff --git a/docs/kcl-std/modules/std-array.md b/docs/kcl-std/modules/std-array.md index b1e7b5d32..fc4ff7d3c 100644 --- a/docs/kcl-std/modules/std-array.md +++ b/docs/kcl-std/modules/std-array.md @@ -1,11 +1,11 @@ --- title: "array" subtitle: "Module in std" -excerpt: "" +excerpt: "Functions for manipulating arrays of values. " layout: manual --- - +Functions for manipulating arrays of values. diff --git a/docs/kcl-std/modules/std-math.md b/docs/kcl-std/modules/std-math.md index 04273086a..01fd1c83f 100644 --- a/docs/kcl-std/modules/std-math.md +++ b/docs/kcl-std/modules/std-math.md @@ -1,11 +1,11 @@ --- title: "math" subtitle: "Module in std" -excerpt: "" +excerpt: "Functions for mathematical operations and some useful constants. " layout: manual --- - +Functions for mathematical operations and some useful constants. diff --git a/docs/kcl-std/modules/std-sketch.md b/docs/kcl-std/modules/std-sketch.md index 2adc6c8a0..4bf464d86 100644 --- a/docs/kcl-std/modules/std-sketch.md +++ b/docs/kcl-std/modules/std-sketch.md @@ -1,13 +1,13 @@ --- title: "sketch" subtitle: "Module in std" -excerpt: "" +excerpt: "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.). " layout: manual --- +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. ## Functions and constants diff --git a/docs/kcl-std/modules/std-solid.md b/docs/kcl-std/modules/std-solid.md index 0f05b5df6..c14262d66 100644 --- a/docs/kcl-std/modules/std-solid.md +++ b/docs/kcl-std/modules/std-solid.md @@ -1,11 +1,11 @@ --- title: "solid" subtitle: "Module in std" -excerpt: "" +excerpt: "This module contains functions for modifying solids, e.g., by adding a fillet or chamfer, or removing part of a solid. " layout: manual --- - +This module contains functions for modifying solids, e.g., by adding a fillet or chamfer, or removing part of a solid. diff --git a/docs/kcl-std/modules/std-transform.md b/docs/kcl-std/modules/std-transform.md index 53c50ab9d..5166cb8e5 100644 --- a/docs/kcl-std/modules/std-transform.md +++ b/docs/kcl-std/modules/std-transform.md @@ -1,11 +1,11 @@ --- title: "transform" subtitle: "Module in std" -excerpt: "" +excerpt: "This module contains functions for transforming sketches and solids. " layout: manual --- - +This module contains functions for transforming sketches and solids. diff --git a/docs/kcl-std/modules/std-turns.md b/docs/kcl-std/modules/std-turns.md index 104dd6c7d..8bb7ee7ee 100644 --- a/docs/kcl-std/modules/std-turns.md +++ b/docs/kcl-std/modules/std-turns.md @@ -1,11 +1,11 @@ --- title: "turns" subtitle: "Module in std" -excerpt: "" +excerpt: "This module contains a few handy constants for defining turns. " layout: manual --- - +This module contains a few handy constants for defining turns. diff --git a/docs/kcl-std/modules/std-types.md b/docs/kcl-std/modules/std-types.md index 88359cb0e..512ec2f9b 100644 --- a/docs/kcl-std/modules/std-types.md +++ b/docs/kcl-std/modules/std-types.md @@ -1,13 +1,13 @@ --- title: "types" subtitle: "Module in std" -excerpt: "" +excerpt: "KCL types. This module contains fundamental types like `number`, `string`, `Solid`, and `Sketch`. " layout: manual --- +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. diff --git a/docs/kcl-std/modules/std-units.md b/docs/kcl-std/modules/std-units.md index 9399a7066..004e5fbda 100644 --- a/docs/kcl-std/modules/std-units.md +++ b/docs/kcl-std/modules/std-units.md @@ -7,7 +7,9 @@ layout: manual 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). ## Functions and constants diff --git a/docs/kcl-std/modules/std.md b/docs/kcl-std/modules/std.md index 648696563..545510dd9 100644 --- a/docs/kcl-std/modules/std.md +++ b/docs/kcl-std/modules/std.md @@ -9,6 +9,8 @@ The KCL standard library 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. + ## Modules * [`array`](/docs/kcl-std/modules/std-array) diff --git a/docs/kcl-std/profileStartX.md b/docs/kcl-std/profileStartX.md index 5bfd7bdaf..26f4b1759 100644 --- a/docs/kcl-std/profileStartX.md +++ b/docs/kcl-std/profileStartX.md @@ -21,7 +21,7 @@ profileStartX(@profile: Sketch): number ### Returns -[`number`](/docs/kcl-std/types/std-types-number) - A number +[`number`](/docs/kcl-std/types/std-types-number) - A number. ### Examples diff --git a/docs/kcl-std/profileStartY.md b/docs/kcl-std/profileStartY.md index ba1ba1659..fd2575325 100644 --- a/docs/kcl-std/profileStartY.md +++ b/docs/kcl-std/profileStartY.md @@ -21,7 +21,7 @@ profileStartY(@profile: Sketch): number ### Returns -[`number`](/docs/kcl-std/types/std-types-number) - A number +[`number`](/docs/kcl-std/types/std-types-number) - A number. ### Examples diff --git a/docs/kcl-std/segAng.md b/docs/kcl-std/segAng.md index 0714f7176..1000add88 100644 --- a/docs/kcl-std/segAng.md +++ b/docs/kcl-std/segAng.md @@ -21,7 +21,7 @@ segAng(@tag: TagIdentifier): number ### Returns -[`number`](/docs/kcl-std/types/std-types-number) - A number +[`number`](/docs/kcl-std/types/std-types-number) - A number. ### Examples diff --git a/docs/kcl-std/segEndX.md b/docs/kcl-std/segEndX.md index ad5025138..118ca6681 100644 --- a/docs/kcl-std/segEndX.md +++ b/docs/kcl-std/segEndX.md @@ -21,7 +21,7 @@ segEndX(@tag: TagIdentifier): number ### Returns -[`number`](/docs/kcl-std/types/std-types-number) - A number +[`number`](/docs/kcl-std/types/std-types-number) - A number. ### Examples diff --git a/docs/kcl-std/segEndY.md b/docs/kcl-std/segEndY.md index 5a8db3dfa..a082d679a 100644 --- a/docs/kcl-std/segEndY.md +++ b/docs/kcl-std/segEndY.md @@ -21,7 +21,7 @@ segEndY(@tag: TagIdentifier): number ### Returns -[`number`](/docs/kcl-std/types/std-types-number) - A number +[`number`](/docs/kcl-std/types/std-types-number) - A number. ### Examples diff --git a/docs/kcl-std/segLen.md b/docs/kcl-std/segLen.md index 91aeec412..eca51db2a 100644 --- a/docs/kcl-std/segLen.md +++ b/docs/kcl-std/segLen.md @@ -21,7 +21,7 @@ segLen(@tag: TagIdentifier): number ### Returns -[`number`](/docs/kcl-std/types/std-types-number) - A number +[`number`](/docs/kcl-std/types/std-types-number) - A number. ### Examples diff --git a/docs/kcl-std/segStartX.md b/docs/kcl-std/segStartX.md index fbc9bf300..e9966c722 100644 --- a/docs/kcl-std/segStartX.md +++ b/docs/kcl-std/segStartX.md @@ -21,7 +21,7 @@ segStartX(@tag: TagIdentifier): number ### Returns -[`number`](/docs/kcl-std/types/std-types-number) - A number +[`number`](/docs/kcl-std/types/std-types-number) - A number. ### Examples diff --git a/docs/kcl-std/segStartY.md b/docs/kcl-std/segStartY.md index 88c12dc62..e64414af1 100644 --- a/docs/kcl-std/segStartY.md +++ b/docs/kcl-std/segStartY.md @@ -21,7 +21,7 @@ segStartY(@tag: TagIdentifier): number ### Returns -[`number`](/docs/kcl-std/types/std-types-number) - A number +[`number`](/docs/kcl-std/types/std-types-number) - A number. ### Examples diff --git a/docs/kcl-std/tangentToEnd.md b/docs/kcl-std/tangentToEnd.md index 2e46abd7a..452060dc3 100644 --- a/docs/kcl-std/tangentToEnd.md +++ b/docs/kcl-std/tangentToEnd.md @@ -21,7 +21,7 @@ tangentToEnd(@tag: TagIdentifier): number ### Returns -[`number`](/docs/kcl-std/types/std-types-number) - A number +[`number`](/docs/kcl-std/types/std-types-number) - A number. ### Examples diff --git a/docs/kcl-std/types/std-types-Axis2d.md b/docs/kcl-std/types/std-types-Axis2d.md index ef2ba1381..4de246b8a 100644 --- a/docs/kcl-std/types/std-types-Axis2d.md +++ b/docs/kcl-std/types/std-types-Axis2d.md @@ -1,11 +1,11 @@ --- title: "Axis2d" subtitle: "Type in std::types" -excerpt: "An infinite line in 2d space." +excerpt: "An abstract and infinite line in 2d space." layout: manual --- -An infinite line in 2d space. +An abstract and infinite line in 2d space. diff --git a/docs/kcl-std/types/std-types-Axis3d.md b/docs/kcl-std/types/std-types-Axis3d.md index 571c60a43..e14f5d64b 100644 --- a/docs/kcl-std/types/std-types-Axis3d.md +++ b/docs/kcl-std/types/std-types-Axis3d.md @@ -1,11 +1,11 @@ --- title: "Axis3d" subtitle: "Type in std::types" -excerpt: "An infinite line in 3d space." +excerpt: "An abstract and infinite line in 3d space." layout: manual --- -An infinite line in 3d space. +An abstract and infinite line in 3d space. diff --git a/docs/kcl-std/types/std-types-Edge.md b/docs/kcl-std/types/std-types-Edge.md index ef5556420..e4e5f94ac 100644 --- a/docs/kcl-std/types/std-types-Edge.md +++ b/docs/kcl-std/types/std-types-Edge.md @@ -1,11 +1,11 @@ --- title: "Edge" subtitle: "Type in std::types" -excerpt: "The edge of a solid." +excerpt: "An edge of a solid." layout: manual --- -The edge of a solid. +An edge of a solid. diff --git a/docs/kcl-std/types/std-types-Face.md b/docs/kcl-std/types/std-types-Face.md index 76e43631e..06c2347e6 100644 --- a/docs/kcl-std/types/std-types-Face.md +++ b/docs/kcl-std/types/std-types-Face.md @@ -1,11 +1,11 @@ --- title: "Face" subtitle: "Type in std::types" -excerpt: "A face." +excerpt: "A face of a solid." layout: manual --- -A face. +A face of a solid. diff --git a/docs/kcl-std/types/std-types-Helix.md b/docs/kcl-std/types/std-types-Helix.md index 8a8d87a3b..7045b8b31 100644 --- a/docs/kcl-std/types/std-types-Helix.md +++ b/docs/kcl-std/types/std-types-Helix.md @@ -1,11 +1,11 @@ --- title: "Helix" subtitle: "Type in std::types" -excerpt: "A helix." +excerpt: "A helix; created by the `helix` function." layout: manual --- -A helix. +A helix; created by the `helix` function. diff --git a/docs/kcl-std/types/std-types-Plane.md b/docs/kcl-std/types/std-types-Plane.md index 8eb32e91c..fe74760ef 100644 --- a/docs/kcl-std/types/std-types-Plane.md +++ b/docs/kcl-std/types/std-types-Plane.md @@ -1,13 +1,14 @@ --- title: "Plane" subtitle: "Type in std::types" -excerpt: "A plane." +excerpt: "An abstract plane." layout: manual --- -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. diff --git a/docs/kcl-std/types/std-types-Solid.md b/docs/kcl-std/types/std-types-Solid.md index 86994767a..b0cc60334 100644 --- a/docs/kcl-std/types/std-types-Solid.md +++ b/docs/kcl-std/types/std-types-Solid.md @@ -1,11 +1,11 @@ --- title: "Solid" subtitle: "Type in std::types" -excerpt: "A solid is a collection of extrude surfaces." +excerpt: "A solid is a collection of extruded surfaces." layout: manual --- -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: diff --git a/docs/kcl-std/types/std-types-any.md b/docs/kcl-std/types/std-types-any.md index 41b65b611..011c17fed 100644 --- a/docs/kcl-std/types/std-types-any.md +++ b/docs/kcl-std/types/std-types-any.md @@ -1,13 +1,28 @@ --- title: "any" subtitle: "Type in std::types" -excerpt: "Any value." +excerpt: "" layout: manual --- -Any value. - - + + +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. + + +### Examples + +```kcl +fn acceptAnything(@input: any) { + return true +} + +acceptAnything(42) +acceptAnything('hello') +acceptAnything(XY) +acceptAnything([0, 1, 2]) +``` diff --git a/docs/kcl-std/types/std-types-bool.md b/docs/kcl-std/types/std-types-bool.md index 9c3119f93..2473778f8 100644 --- a/docs/kcl-std/types/std-types-bool.md +++ b/docs/kcl-std/types/std-types-bool.md @@ -7,7 +7,7 @@ layout: manual A boolean value. -`true` or `false` +`true` or `false`. diff --git a/docs/kcl-std/types/std-types-number.md b/docs/kcl-std/types/std-types-number.md index 81261073d..79f71626b 100644 --- a/docs/kcl-std/types/std-types-number.md +++ b/docs/kcl-std/types/std-types-number.md @@ -1,15 +1,28 @@ --- title: "number" subtitle: "Type in std::types" -excerpt: "A number" +excerpt: "A number." layout: manual --- -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)`](/docs/kcl-std/types/std-types-number). 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`](/docs/kcl-std/types/std-types-number) type may or may not include units, if none are specified, then +it is the type of any number. E.g., + +- [`number`](/docs/kcl-std/types/std-types-number): the type of any numbers, +- [`number(mm)`](/docs/kcl-std/types/std-types-number): the type of numbers in millimeters, +- [`number(in)`](/docs/kcl-std/types/std-types-number): the type of numbers in inches, +- [`number(Length)`](/docs/kcl-std/types/std-types-number): the type of numbers in any length unit, +- [`number(deg)`](/docs/kcl-std/types/std-types-number): the type of numbers in degrees, +- [`number(Angle)`](/docs/kcl-std/types/std-types-number): the type of numbers in any angle unit, +- [`number(_)`](/docs/kcl-std/types/std-types-number) or [`number(Count)`](/docs/kcl-std/types/std-types-number): 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). diff --git a/rust/kcl-lib/std/array.kcl b/rust/kcl-lib/std/array.kcl index fb6b4ed81..33759f2ac 100644 --- a/rust/kcl-lib/std/array.kcl +++ b/rust/kcl-lib/std/array.kcl @@ -1,2 +1,4 @@ +/// Functions for manipulating arrays of values. + @no_std @settings(defaultLengthUnit = mm, kclVersion = 1.0) diff --git a/rust/kcl-lib/std/math.kcl b/rust/kcl-lib/std/math.kcl index d5d292796..a8cff57d2 100644 --- a/rust/kcl-lib/std/math.kcl +++ b/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) diff --git a/rust/kcl-lib/std/prelude.kcl b/rust/kcl-lib/std/prelude.kcl index 01ec550f3..7cee26d2b 100644 --- a/rust/kcl-lib/std/prelude.kcl +++ b/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], diff --git a/rust/kcl-lib/std/sketch.kcl b/rust/kcl-lib/std/sketch.kcl index 59a881c08..cebb53dad 100644 --- a/rust/kcl-lib/std/sketch.kcl +++ b/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) diff --git a/rust/kcl-lib/std/solid.kcl b/rust/kcl-lib/std/solid.kcl index ad1858bb0..8e23028ac 100644 --- a/rust/kcl-lib/std/solid.kcl +++ b/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) diff --git a/rust/kcl-lib/std/transform.kcl b/rust/kcl-lib/std/transform.kcl index c2fc0eb7a..b2c30bb88 100644 --- a/rust/kcl-lib/std/transform.kcl +++ b/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. diff --git a/rust/kcl-lib/std/turns.kcl b/rust/kcl-lib/std/turns.kcl index 0ea814515..e32776a59 100644 --- a/rust/kcl-lib/std/turns.kcl +++ b/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 diff --git a/rust/kcl-lib/std/types.kcl b/rust/kcl-lib/std/types.kcl index c41102d37..315fcfec1 100644 --- a/rust/kcl-lib/std/types.kcl +++ b/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 diff --git a/rust/kcl-lib/std/units.kcl b/rust/kcl-lib/std/units.kcl index 6f4aaca69..3f23a4bba 100644 --- a/rust/kcl-lib/std/units.kcl +++ b/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)