Merge pull request #411 from hannobraun/syntax

Improve documentation of `fj` crate

fj/src/lib.rs

@@ -10,23 +10,22 @@
 //!
 //! [Fornjot repository]: https://github.com/hannobraun/Fornjot
 
+#![deny(missing_docs)]
+
+pub mod syntax;
+
 mod shape_2d;
 mod shape_3d;
-mod syntax;
-
-pub mod prelude {
-    pub use crate::syntax::{
-        Difference as _, Group as _, Rotate as _, Sketch as _, Sweep as _,
-        Translate as _,
-    };
-}
 
 pub use self::{shape_2d::*, shape_3d::*};
 
 /// A shape
 #[derive(Clone, Debug)]
 #[repr(C)]
 pub enum Shape {
+    /// A 2D shape
     Shape2d(Shape2d),
+
+    /// A 3D shape
     Shape3d(Shape3d),
 }

fj/src/shape_2d.rs

@@ -46,6 +46,7 @@ impl Circle {
         }
     }
 
+    /// Access the circle's radius
     pub fn radius(&self) -> f64 {
         self.radius
     }
@@ -91,6 +92,7 @@ pub struct Difference2d {
 }
 
 impl Difference2d {
+    /// Create a `Difference2d` from two shapes
     pub fn from_objects(a: Shape2d, b: Shape2d) -> Self {
         Self { a, b }
     }
@@ -100,10 +102,12 @@ impl Difference2d {
         self.a.color()
     }
 
+    /// Access the original shape
     pub fn a(&self) -> &Shape2d {
         &self.a
     }
 
+    /// Access the shape being subtracted
     pub fn b(&self) -> &Shape2d {
         &self.b
     }

fj/src/shape_3d.rs

@@ -99,18 +99,22 @@ pub struct Sweep {
 }
 
 impl Sweep {
+    /// Create a `Sweep` from a shape and a length
     pub fn from_shape_and_length(shape: Shape2d, length: f64) -> Self {
         Self { shape, length }
     }
 
+    /// Access the shape being swept
     pub fn shape(&self) -> &Shape2d {
         &self.shape
     }
 
+    /// Access the length of the sweep
     pub fn length(&self) -> f64 {
         self.length
     }
 
+    /// Access the color of the shape being swept
     pub fn color(&self) -> [u8; 4] {
         self.shape().color()
     }

fj/src/syntax.rs

@@ -1,4 +1,13 @@
+//! Convenient syntax for `fj` operations
+//!
+//! This model defines extension traits, which provide convenient syntax for
+//! the various operations defined in this trait.
+
+/// Convenient syntax to create an [`fj::Difference2d`]
+///
+/// [`fj::Difference2d`]: crate::Difference2d
 pub trait Difference {
+    /// Create a difference between `self` and `other`
     fn difference<Other>(&self, other: &Other) -> crate::Difference2d
     where
         Other: Clone + Into<crate::Shape2d>;
@@ -19,7 +28,11 @@ where
     }
 }
 
+/// Convenient syntax to create an [`fj::Group`]
+///
+/// [`fj::Group`]: crate::Group
 pub trait Group {
+    /// Create a group with `self` and `other`
     fn group<Other>(&self, other: &Other) -> crate::Group
     where
         Other: Clone + Into<crate::Shape3d>;
@@ -40,6 +53,9 @@ where
     }
 }
 
+/// Convenient syntax to create an [`fj::Transform`]
+///
+/// [`fj::Transform`]: crate::Transform
 pub trait Rotate {
     /// Create a rotation
     ///
@@ -63,7 +79,14 @@ where
     }
 }
 
+/// Convenient syntax to create an [`fj::Sketch`]
+///
+/// [`fj::Sketch`]: crate::Sketch
 pub trait Sketch {
+    /// Create a sketch from `self`
+    ///
+    /// Can be called on any type that implements `AsRef<[[f64; 2]]`, which is
+    /// implemented for types like slices, arrays, or `Vec`.
     fn sketch(&self) -> crate::Sketch;
 }
 
@@ -76,7 +99,11 @@ where
     }
 }
 
+/// Convenient syntax to create an [`fj::Sweep`]
+///
+/// [`fj::Sweep`]: crate::Sweep
 pub trait Sweep {
+    /// Sweep `self` along the z-axis by `length`
     fn sweep(&self, length: f64) -> crate::Sweep;
 }
 
@@ -90,6 +117,9 @@ where
     }
 }
 
+/// Convenient syntax to create an [`fj::Transform`]
+///
+/// [`fj::Transform`]: crate::Transform
 pub trait Translate {
     /// Create a translation
     ///

models/group/src/lib.rs

@@ -1,6 +1,6 @@
 use std::collections::HashMap;
 
-use fj::prelude::*;
+use fj::syntax::*;
 
 #[no_mangle]
 pub extern "C" fn model(_: &HashMap<String, String>) -> fj::Shape {

models/spacer/src/lib.rs

@@ -1,6 +1,6 @@
 use std::collections::HashMap;
 
-use fj::prelude::*;
+use fj::syntax::*;
 
 #[no_mangle]
 pub extern "C" fn model(args: &HashMap<String, String>) -> fj::Shape {