From ac3fee6314782c7481a865333d6e587c96af452b Mon Sep 17 00:00:00 2001 From: Hanno Braun Date: Tue, 29 Mar 2022 17:40:37 +0200 Subject: [PATCH 1/5] Make `fj::syntax` public Having its traits exposed only through `prelude` results in pretty useless documentation. There's really no reason to not make `syntax` itself public instead. --- fj/src/lib.rs | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/fj/src/lib.rs b/fj/src/lib.rs index 2cf19969c..b4b317e0c 100644 --- a/fj/src/lib.rs +++ b/fj/src/lib.rs @@ -10,9 +10,10 @@ //! //! [Fornjot repository]: https://github.com/hannobraun/Fornjot +pub mod syntax; + mod shape_2d; mod shape_3d; -mod syntax; pub mod prelude { pub use crate::syntax::{ From 88b43688f3ed56f8ecaea713fcd71a3313c4034c Mon Sep 17 00:00:00 2001 From: Hanno Braun Date: Tue, 29 Mar 2022 17:42:24 +0200 Subject: [PATCH 2/5] Remove `fj::prelude` With `syntax` now public, it's become redundant. --- fj/src/lib.rs | 7 ------- models/group/src/lib.rs | 2 +- models/spacer/src/lib.rs | 2 +- 3 files changed, 2 insertions(+), 9 deletions(-) diff --git a/fj/src/lib.rs b/fj/src/lib.rs index b4b317e0c..dc93934ba 100644 --- a/fj/src/lib.rs +++ b/fj/src/lib.rs @@ -15,13 +15,6 @@ pub mod syntax; mod shape_2d; mod shape_3d; -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 diff --git a/models/group/src/lib.rs b/models/group/src/lib.rs index 5892eafb4..93b370544 100644 --- a/models/group/src/lib.rs +++ b/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) -> fj::Shape { diff --git a/models/spacer/src/lib.rs b/models/spacer/src/lib.rs index 16af20e4a..27fb9a2b4 100644 --- a/models/spacer/src/lib.rs +++ b/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) -> fj::Shape { From 5b217605b8d97c20c50e4c319c1dab7b01005727 Mon Sep 17 00:00:00 2001 From: Hanno Braun Date: Tue, 29 Mar 2022 17:50:57 +0200 Subject: [PATCH 3/5] Document `fj::Syntax` --- fj/src/syntax.rs | 30 ++++++++++++++++++++++++++++++ 1 file changed, 30 insertions(+) diff --git a/fj/src/syntax.rs b/fj/src/syntax.rs index e79696a08..0422cb0ce 100644 --- a/fj/src/syntax.rs +++ b/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(&self, other: &Other) -> crate::Difference2d where Other: Clone + Into; @@ -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(&self, other: &Other) -> crate::Group where Other: Clone + Into; @@ -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 /// From 335598fe521f5eece16e9808b690ce0802e60b28 Mon Sep 17 00:00:00 2001 From: Hanno Braun Date: Tue, 29 Mar 2022 17:56:22 +0200 Subject: [PATCH 4/5] Add missing documentation in `fj` --- fj/src/lib.rs | 3 +++ fj/src/shape_2d.rs | 4 ++++ fj/src/shape_3d.rs | 4 ++++ 3 files changed, 11 insertions(+) diff --git a/fj/src/lib.rs b/fj/src/lib.rs index dc93934ba..da2258b36 100644 --- a/fj/src/lib.rs +++ b/fj/src/lib.rs @@ -21,6 +21,9 @@ pub use self::{shape_2d::*, shape_3d::*}; #[derive(Clone, Debug)] #[repr(C)] pub enum Shape { + /// A 2D shape Shape2d(Shape2d), + + /// A 3D shape Shape3d(Shape3d), } diff --git a/fj/src/shape_2d.rs b/fj/src/shape_2d.rs index 61b4de9dd..50aae3b8f 100644 --- a/fj/src/shape_2d.rs +++ b/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 } diff --git a/fj/src/shape_3d.rs b/fj/src/shape_3d.rs index 0491f2d27..be6ae2ba1 100644 --- a/fj/src/shape_3d.rs +++ 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() } From 7b2656f9fde8daa0aaf23938e7121da69049f6b3 Mon Sep 17 00:00:00 2001 From: Hanno Braun Date: Tue, 29 Mar 2022 17:56:33 +0200 Subject: [PATCH 5/5] Deny missing documentation in `fj` --- fj/src/lib.rs | 2 ++ 1 file changed, 2 insertions(+) diff --git a/fj/src/lib.rs b/fj/src/lib.rs index da2258b36..7bdd0d0b6 100644 --- a/fj/src/lib.rs +++ b/fj/src/lib.rs @@ -10,6 +10,8 @@ //! //! [Fornjot repository]: https://github.com/hannobraun/Fornjot +#![deny(missing_docs)] + pub mod syntax; mod shape_2d;