More docs for Plane, Pi, etc. (#6850)

* Document the units of PI

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

* Add links between lang and std references

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

* Change signature of conversion functions

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

* Split foreign imports out of modules docs

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

* More docs for Plane

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

* Update docs/kcl-std/consts/std-math-PI.md

Co-authored-by: graphite-app[bot] <96075541+graphite-app[bot]@users.noreply.github.com>

* Update rust/kcl-lib/std/math.kcl

Co-authored-by: graphite-app[bot] <96075541+graphite-app[bot]@users.noreply.github.com>

---------

Signed-off-by: Nick Cameron <nrc@ncameron.org>
Co-authored-by: Jess Frazelle <jessfraz@users.noreply.github.com>
Co-authored-by: graphite-app[bot] <96075541+graphite-app[bot]@users.noreply.github.com>

rust/kcl-lib/std/math.kcl

@@ -7,6 +7,14 @@ import Point2d from "std::types"
 
 /// The value of `pi`, Archimedes’ constant (π).
 ///
+/// `PI` is a number and is technically a ratio, so you might expect it to have type `number(_)`.
+/// However, `PI` is nearly always used for converting between different units - usually degrees to or
+/// from radians. Therefore, `PI` is treated a bit specially by KCL and always has unknown units. This
+/// means that if you use `PI`, you will need to give KCL some extra information about the units of numbers.
+/// Usually you should use type ascription on the result of calculations, e.g., `(2 * PI): number(rad)`.
+/// You might prefer to use `units::toRadians` or `units::toDegrees` to convert between angles with
+/// different units.
+///
 /// ```
 /// circumference = 70
 ///

rust/kcl-lib/std/prelude.kcl

@@ -5,6 +5,8 @@
 ///
 /// The standard library is organised into modules (listed below), but most things are always available
 /// in KCL programs.
+///
+/// You might also want the [KCL language reference](/docs/kcl-lang) or the [KCL guide]().
 
 @no_std
 @settings(defaultLengthUnit = mm, kclVersion = 1.0)

rust/kcl-lib/std/types.kcl

@@ -165,8 +165,25 @@ export type tag
 
 /// 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.
+/// A plane has a position and orientation in space defined by its origin and axes. A plane is abstract
+/// in the sense that it is not part of the objects being drawn. A plane can be used to sketch on.
+///
+/// A plane can be created in several ways:
+/// - you can use one of the default planes, e.g., `XY`.
+/// - you can use `offsetPlane` to create a new plane offset from an existing one, e.g., `offsetPlane(XY, offset = 150)`.
+/// - you can use negation to create a plane from an existing one which is identical but has an opposite normal
+/// e.g., `-XY`.
+/// - you can define an entirely custom plane, e.g.,
+///
+/// ```kcl,inline,norun
+/// myXY = {
+///   origin = { x = 0, y = 0, z = 0 },
+///   xAxis = { x = 1, y = 0, z = 0 },
+///   yAxis = { x = 0, y = 1, z = 0 },
+/// }
+/// ```
+///
+/// Any object with appropriate `origin`, `xAxis`, and `yAxis` fields can be used as a plane.
 @(impl = std_rust)
 export type Plane
 

rust/kcl-lib/std/units.kcl

@@ -11,32 +11,32 @@
 @settings(defaultLengthUnit = mm, kclVersion = 1.0)
 
 /// Convert a number to millimeters from its current units.
-export fn toMillimeters(@num: number(mm)): number(mm) {
+export fn toMillimeters(@num: number(Length)): number(mm) {
   return num
 }
 
 /// Convert a number to centimeters from its current units.
-export fn toCentimeters(@num: number(cm)): number(cm) {
+export fn toCentimeters(@num: number(Length)): number(cm) {
   return num
 }
 
 /// Convert a number to meters from its current units.
-export fn toMeters(@num: number(m)): number(m) {
+export fn toMeters(@num: number(Length)): number(m) {
   return num
 }
 
 /// Convert a number to inches from its current units.
-export fn toInches(@num: number(in)): number(in) {
+export fn toInches(@num: number(Length)): number(in) {
   return num
 }
 
 /// Convert a number to feet from its current units.
-export fn toFeet(@num: number(ft)): number(ft) {
+export fn toFeet(@num: number(Length)): number(ft) {
   return num
 }
 
 /// Converts a number to yards from its current units.
-export fn toYards(@num: number(yd)): number(yd) {
+export fn toYards(@num: number(Length)): number(yd) {
   return num
 }
 
@@ -54,7 +54,7 @@ export fn toYards(@num: number(yd)): number(yd) {
 ///
 /// example = extrude(exampleSketch, length = 5)
 /// ```
-export fn toRadians(@num: number(rad)): number(rad) {
+export fn toRadians(@num: number(Angle)): number(rad) {
   return num
 }
 
@@ -72,6 +72,6 @@ export fn toRadians(@num: number(rad)): number(rad) {
 ///
 /// example = extrude(exampleSketch, length = 5)
 /// ```
-export fn toDegrees(@num: number(deg)): number(deg) {
+export fn toDegrees(@num: number(Angle)): number(deg) {
   return num
 }