Merge pull request #776 from hannobraun/docs

Update some documentation; fix remaining doc warnings

crates/fj-kernel/src/objects/cycle.rs

@@ -40,10 +40,7 @@ impl Cycle {
         Cycle { edges }
     }
 
-    /// Access the edges that this cycle refers to
+    /// Access this cycle's edges
-    ///
-    /// This is a convenience method that saves the caller from dealing with the
-    /// [`Handle`]s.
     pub fn edges(&self) -> impl Iterator<Item = Edge> + '_ {
         self.edges.iter().cloned()
     }

crates/fj-kernel/src/objects/edge.rs

@@ -76,18 +76,12 @@ impl Edge {
         }
     }
 
-    /// Access the curve that the edge refers to
+    /// Access this edge's curve
-    ///
-    /// This is a convenience method that saves the caller from dealing with the
-    /// [`Handle`].
     pub fn curve(&self) -> Curve<3> {
         self.curve.global()
     }
 
-    /// Access the vertices that the edge refers to
+    /// Access this edge's vertices
-    ///
-    /// This is a convenience method that saves the caller from dealing with the
-    /// [`Handle`]s.
     pub fn vertices(&self) -> Option<[Vertex; 2]> {
         self.vertices.0
     }

crates/fj-kernel/src/objects/face.rs

@@ -58,31 +58,22 @@ impl Face {
         }
     }
 
-    /// Access the surface that the face refers to
+    /// Access this face's surface
-    ///
-    /// This is a convenience method that saves the caller from dealing with the
-    /// [`Handle`].
     pub fn surface(&self) -> Surface {
         self.brep().surface()
     }
 
-    /// Access the exterior cycles that the face refers to
+    /// Access this face's exterior cycles
-    ///
-    /// This is a convenience method that saves the caller from dealing with the
-    /// [`Handle`]s.
     pub fn exteriors(&self) -> impl Iterator<Item = Cycle> + '_ {
         self.brep().exteriors()
     }
 
-    /// Access the interior cycles that the face refers to
+    /// Access this face's interior cycles
-    ///
-    /// This is a convenience method that saves the caller from dealing with the
-    /// [`Handle`]s.
     pub fn interiors(&self) -> impl Iterator<Item = Cycle> + '_ {
         self.brep().interiors()
     }
 
-    /// Access all cycles that the face refers to
+    /// Access all cycles of this face
     ///
     /// This is equivalent to chaining the iterators returned by
     /// [`Face::exteriors`] and [`Face::interiors`].
@@ -132,31 +123,22 @@ pub struct FaceBRep {
 }
 
 impl FaceBRep {
-    /// Access the surface that the face refers to
+    /// Access this face's surface
-    ///
-    /// This is a convenience method that saves the caller from dealing with the
-    /// [`Handle`].
     pub fn surface(&self) -> Surface {
         self.surface
     }
 
-    /// Access the exterior cycles that the face refers to
+    /// Access this face's exterior cycles
-    ///
-    /// This is a convenience method that saves the caller from dealing with the
-    /// [`Handle`]s.
     pub fn exteriors(&self) -> impl Iterator<Item = Cycle> + '_ {
         self.exteriors.as_local()
     }
 
-    /// Access the interior cycles that the face refers to
+    /// Access this face's interior cycles
-    ///
-    /// This is a convenience method that saves the caller from dealing with the
-    /// [`Handle`]s.
     pub fn interiors(&self) -> impl Iterator<Item = Cycle> + '_ {
         self.interiors.as_local()
     }
 
-    /// Access all cycles that the face refers to
+    /// Access all cycles of this face
     ///
     /// This is equivalent to chaining the iterators returned by
     /// [`Face::exteriors`] and [`Face::interiors`].

crates/fj-kernel/src/objects/global_vertex.rs

@@ -16,8 +16,10 @@ use fj_math::Point;
 /// Vertices must be unique within a shape, meaning an identical vertex must not
 /// exist in the same shape. In the context of vertex uniqueness, points that
 /// are close to each other are considered identical. The minimum distance
-/// between distinct vertices can be configured using
+/// between distinct vertices can be configured using the respective field in
-/// [`Shape::with_minimum_distance`].
+/// [`ValidationConfig`].
+///
+/// [`ValidationConfig`]: crate::validation::ValidationConfig
 #[derive(Clone, Copy, Debug, Eq, PartialEq, Hash, Ord, PartialOrd)]
 pub struct GlobalVertex {
     position: Point<3>,

crates/fj-kernel/src/validation/mod.rs

@@ -13,17 +13,6 @@
 //!
 //! Please note that not all of these validation categories are fully
 //! implemented, as of this writing.
-//!
-//! # Implementation Note
-//!
-//! There is an ongoing effort to abolish [`Shape`] and replace it with a much
-//! simpler data structure:
-//! <https://github.com/hannobraun/Fornjot/issues/697>
-//!
-//! Once completed, this would make structural validation moot, and reduce the
-//! scope of uniqueness validation.
-//!
-//! [`Shape`]: crate::shape::Shape
 
 mod coherence;
 mod uniqueness;
@@ -39,7 +28,7 @@ use fj_math::Scalar;
 
 use crate::iter::ObjectIters;
 
-/// Validate the given [`Shape`]
+/// Validate the given object
 pub fn validate<T>(
     object: T,
     config: &ValidationConfig,