Update documentation of partial object API

crates/fj-kernel/src/partial/maybe_partial.rs

@@ -7,7 +7,15 @@ use crate::{
 
 use super::{HasPartial, Partial};
 
-/// Either a partial object or a full one
+/// Can be used everywhere either a partial or full objects are accepted
+///
+/// Some convenience methods are available for specific instances of
+/// `MaybePartial` (like, `MaybePartial<Curve>`, or `MaybePartial<Vertex>`).
+///
+/// # Implementation Note
+///
+/// The set of available convenience methods is far from complete. Please feel
+/// free to just add more, if you need them.
 #[derive(Clone, Copy, Debug, Eq, PartialEq, Hash, Ord, PartialOrd)]
 pub enum MaybePartial<T: HasPartial> {
     /// A full object
@@ -19,6 +27,10 @@ pub enum MaybePartial<T: HasPartial> {
 
 impl<T: HasPartial> MaybePartial<T> {
     /// If this is a partial object, update it
+    ///
+    /// This is useful whenever a partial object can infer something about its
+    /// parts from other parts, and wants to update what was inferred, in case
+    /// it *can* be updated.
     pub fn update_partial(
         self,
         f: impl FnOnce(T::Partial) -> T::Partial,
@@ -29,15 +41,22 @@ impl<T: HasPartial> MaybePartial<T> {
         }
     }
 
-    /// Return the full object, either directly or by building it
+    /// Return or build a full object
+    ///
+    /// If this already is a full object, it is returned. If this is a partial
+    /// object, the full object is built from it, using [`Partial::build`].
     pub fn into_full(self, stores: &Stores) -> T {
         match self {
             Self::Partial(partial) => partial.build(stores),
             Self::Full(full) => full,
         }
     }
 
-    /// Return the partial object, either directly or via conversion
+    /// Return or convert a partial object
+    ///
+    /// If this already is a partial object, is is returned. If this is a full
+    /// object, it is converted into a partial object using
+    /// [`HasPartial::to_partial`].
     pub fn into_partial(self) -> T::Partial {
         match self {
             Self::Partial(partial) => partial,

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

@@ -1,29 +1,36 @@
-//! Partial objects
+//! API for dealing with partially defined objects
 //!
-//! This module contains type that represent partial objects. This is useful
-//! when building objects, as it's often possible to provide just some the data
-//! they own or objects they reference, while computing the rest.
+//! This module contains types that represent objects that only have some of
+//! their data and referenced objects defined. This is useful in the following
+//! situations:
 //!
-//! More generally speaking, there are situations where different parts of a new
-//! objects are available at different times, and provided from different
-//! places. Partial objects can be used to represent such partially constructed
-//! objects whenever that is required.
+//! - Sometimes parts of an object can be inferred. For example, when building a
+//!   half-edge that is a line segment, it is enough to provide only two partial
+//!   vertices with only their surface coordinates defined. The rest can be
+//!   inferred.
+//! - Sometimes you need to build an object, but parts of it already exist. For
+//!   example, a new half-edge might share a vertex with an existing half-edge.
+//!   In such a case you can use the partial object to provide the existing
+//!   vertex, then provide or infer other parts as appropriate.
+//! - When transforming an object, parts of it might already be transformed. For
+//!   example, when transforming a half-edge, each of its vertices references
+//!   the same curve as the half-edge does. The partial object API can be used
+//!   to avoid transforming the same object multiple times.
 //!
-//! The API for partial objects follows a specific style:
+//! This module contains two groups of types:
 //!
-//! - Partial objects are structs with fields that mirror the fields of the full
-//!   object structs, but all fields are optional.
-//! - Partial object structs implement [`Default`], but a `partial` method is
-//!   also available on the respective full object struct, as a perhaps more
-//!   convenient and readable way to construct a partial object.
-//! - Partial object structs have `with_*` methods to provide values for each of
-//!   their fields.
-//! - Partial object structs may have other methods with prefixes like `as_*`,
-//!   `from_*`, or similar, if one or more of their fields can be initialized by
-//!   providing alternative data.
-//! - Partial object structs have a `build` method to build a full object.
-//! - All `with_*`, `as_*`, and `build` methods can be chained, to provide a
-//!   convenient API.
+//! - Structs that represent partial objects. For example [`PartialHalfEdge`] is
+//!   the partial variant of [`HalfEdge`].
+//! - Infrastructure for abstracting over partial objects. See [`Partial`],
+//!   [`HasPartial`], and [`MaybePartial`].
+//!
+//! # Implementation Note
+//!
+//! This API grew out of the [builder API][crate::builder] and is still
+//! incomplete. Eventually, it should replace the builder API completely
+//! ([#1147]).
+//!
+//! [#1147]: https://github.com/hannobraun/Fornjot/issues/1147
 
 mod maybe_partial;
 mod objects;

crates/fj-kernel/src/partial/traits.rs

@@ -1,6 +1,6 @@
 use crate::stores::Stores;
 
-/// Implemented for types that are partial objects
+/// Implemented for objects that a partial object type exists for
 ///
 /// # Implementation Note
 ///
@@ -17,7 +17,7 @@ use crate::stores::Stores;
 /// [#1021]: https://github.com/hannobraun/Fornjot/issues/1021
 /// [`MaybePartial`]: super::MaybePartial
 pub trait HasPartial {
-    /// The full version of this partial object
+    /// The type representing the partial variant of this object
     type Partial: Partial<Full = Self>;
 
     /// Create an empty partial variant of this object
@@ -40,6 +40,19 @@ pub trait HasPartial {
 
 /// Implemented for partial objects
 ///
+/// The API for partial objects follows a specific style:
+///
+/// - Partial objects are structs with fields that mirror the fields of the full
+///   object structs, but all fields are optional.
+/// - Partial object structs have `with_*` methods to provide values for each of
+///   their fields.
+/// - Partial object structs may have other methods with prefixes like `as_*`,
+///   `from_*`, or similar, if one or more of their fields can be initialized by
+///   providing alternative data.
+/// - Partial object structs have a `build` method to build a full object.
+/// - All `with_*`, `as_*`, and `build` methods can be chained, to provide a
+///   convenient API.
+///
 /// # Implementation Note
 ///
 /// It would be nicer to require an [`Into`] bound instead of [`From`] (see