From 89838e905c704d827903d62484c66b8f52c77850 Mon Sep 17 00:00:00 2001
From: Hanno Braun <hanno@braun-odw.eu>
Date: Fri, 23 Sep 2022 16:14:26 +0200
Subject: [PATCH] Update documentation of `PartialHalfEdge`

---
 crates/fj-kernel/src/objects/edge.rs |  5 ++++-
 crates/fj-kernel/src/partial/edge.rs | 19 +++++++++----------
 2 files changed, 13 insertions(+), 11 deletions(-)

diff --git a/crates/fj-kernel/src/objects/edge.rs b/crates/fj-kernel/src/objects/edge.rs
index a61910f90d..06ca671685 100644
--- a/crates/fj-kernel/src/objects/edge.rs
+++ b/crates/fj-kernel/src/objects/edge.rs
@@ -16,7 +16,10 @@ pub struct HalfEdge {
 }
 
 impl HalfEdge {
-    /// Build a `HalfEdge` using [`PartialHalfEdge`]
+    /// Create a [`PartialHalfEdge`]
+    ///
+    /// This function exists just for convenience, and will just return a
+    /// default [`PartialHalfEdge`].
     pub fn partial() -> PartialHalfEdge {
         PartialHalfEdge::default()
     }
diff --git a/crates/fj-kernel/src/partial/edge.rs b/crates/fj-kernel/src/partial/edge.rs
index ec1ba49f7b..d604e860e4 100644
--- a/crates/fj-kernel/src/partial/edge.rs
+++ b/crates/fj-kernel/src/partial/edge.rs
@@ -9,9 +9,9 @@ use crate::{
 
 use super::MaybePartial;
 
-/// API for building a [`HalfEdge`]
+/// A partial [`HalfEdge`]
 ///
-/// Also see [`HalfEdge::partial`].
+/// See [`crate::partial`] for more information.
 #[derive(Clone, Debug, Default, Eq, PartialEq, Hash, Ord, PartialOrd)]
 pub struct PartialHalfEdge {
     /// The curve that the [`HalfEdge`] is defined in
@@ -22,19 +22,18 @@ pub struct PartialHalfEdge {
 
     /// The global form of the [`HalfEdge`]
     ///
-    /// Can be provided to the builder, if available, or computed by one of the
-    /// build methods.
+    /// Can be computed by [`PartialHalfEdge::build`], if not available.
     pub global_form: Option<GlobalEdge>,
 }
 
 impl PartialHalfEdge {
-    /// Build the [`HalfEdge`] with the given curve
+    /// Update the partial half-edge with the given curve
     pub fn with_curve(mut self, curve: impl Into<MaybePartial<Curve>>) -> Self {
         self.curve = Some(curve.into());
         self
     }
 
-    /// Build the [`HalfEdge`] with the given vertices
+    /// Update the partial half-edge with the given vertices
     pub fn with_vertices(
         mut self,
         vertices: [impl Into<MaybePartial<Vertex>>; 2],
@@ -43,13 +42,13 @@ impl PartialHalfEdge {
         self
     }
 
-    /// Build the [`HalfEdge`] with the provided global form
+    /// Update the partial half-edge with the given global form
     pub fn with_global_form(mut self, global_form: GlobalEdge) -> Self {
         self.global_form = Some(global_form);
         self
     }
 
-    /// Build the [`HalfEdge`] as a circle from the given radius
+    /// Update partial half-edge as a circle, from the given radius
     pub fn as_circle_from_radius(
         mut self,
         surface: Surface,
@@ -80,7 +79,7 @@ impl PartialHalfEdge {
         self
     }
 
-    /// Build the [`HalfEdge`] as a line segment from the given points
+    /// Update partial half-edge as a line segment, from the given points
     pub fn as_line_segment_from_points(
         mut self,
         surface: Surface,
@@ -102,7 +101,7 @@ impl PartialHalfEdge {
         self
     }
 
-    /// Finish building the [`HalfEdge`]
+    /// Build a full [`HalfEdge`] from the partial half-edge
     pub fn build(self, stores: &Stores) -> HalfEdge {
         let curve = self
             .curve