Merge pull request #1899 from hannobraun/docs

Make some improvements to the documentation

crates/fj-core/src/algorithms/approx/edge.rs

@@ -3,7 +3,7 @@
 //! The approximation of a curve is its first vertex, combined with the
 //! approximation of its curve. The second vertex is left off, as edge
 //! approximations are usually used to build cycle approximations, and this way,
-//! the caller doesn't have to call with duplicate vertices.
+//! the caller doesn't have to deal with duplicate vertices.
 
 use std::collections::BTreeMap;
 

crates/fj-core/src/algorithms/mod.rs

@@ -1,7 +1,14 @@
-//! Collection of algorithms that are used by the kernel
+//! Collection of algorithms that operate on geometry
 //!
 //! Algorithmic code is collected in this module, to keep other modules focused
 //! on their respective purpose.
+//!
+//! # Implementation Note
+//!
+//! This module exists in a bit of an in-between state, as some of the things
+//! that are still here are probably better places in the [`operations`] module.
+//!
+//! [`operations`]: crate::operations
 
 pub mod approx;
 pub mod bounding_volume;

crates/fj-core/src/lib.rs

@@ -14,8 +14,8 @@
 //! explicitness**. This means that geometrical relationships must be expressed
 //! explicitly, or they are not accepted.
 //!
-//! It is important to understand that this principle defines the destination of
-//! CAD kernel development. It does not reflect the current reality.
+//! This principle is not fully implemented yet. There are quite a few
+//! validation checks that enforce part of it, but many are still missing.
 //!
 //! ### Motivation
 //!

crates/fj-math/src/coordinates.rs

@@ -1,13 +1,29 @@
 use super::Scalar;
 
 /// 1-dimensional curve coordinates
+///
+/// One-dimensional [`Point`]s and [`Vector`]s dereference to this type (via
+/// [`Deref`]). This allows you to access the `t` field, even though [`Point`]
+/// and [`Vector`] do not have such a field themselves.
+///
+/// [`Deref`]: std::ops::Deref
+/// [`Point`]: crate::Point
+/// [`Vector`]: crate::Vector
 #[repr(C)]
 pub struct T {
     /// The single coordinate of the 1-dimensional curve coordinates
     pub t: Scalar,
 }
 
 /// 2-dimensional surface coordinates
+///
+/// Two-dimensional [`Point`]s and [`Vector`]s dereference to this type (via
+/// [`Deref`]). This allows you to access the `u`/`v` fields, even though
+/// [`Point`] and [`Vector`] do not have such fields themselves.
+///
+/// [`Deref`]: std::ops::Deref
+/// [`Point`]: crate::Point
+/// [`Vector`]: crate::Vector
 #[repr(C)]
 pub struct Uv {
     /// The first coordinate of the 2-dimensional surface coordinates
@@ -18,6 +34,14 @@ pub struct Uv {
 }
 
 /// 3-dimensional model coordinates
+///
+/// Three-dimensional [`Point`]s and [`Vector`]s dereference to this type (via
+/// [`Deref`]). This allows you to access the `x`/`y`/`z` fields, even though
+/// [`Point`] and [`Vector`] do not have such fields themselves.
+///
+/// [`Deref`]: std::ops::Deref
+/// [`Point`]: crate::Point
+/// [`Vector`]: crate::Vector
 #[repr(C)]
 pub struct Xyz {
     /// The first coordinate of the 3-dimensional model coordinates