Update documentation of objects module

crates/fj-core/src/objects/mod.rs

@@ -1,42 +1,42 @@
-//! Objects of a shape
+//! # Objects of a shape
 //!
-//! Objects, in Fornjot parlance, are the elements that make up shapes. An
-//! object can be simple and just contain data (like [`Vertex`], for example),
-//! or they can be quite complex and refer to other objects (which is actually
-//! most of them).
+//! Objects, in Fornjot parlance, are the elements that make up shapes. Objects
+//! can reference each other, forming a directed acyclic graph (DAG).
 //!
-//! # Object Identity vs Object Equality
+//! There are two top-level objects ([`Sketch`] and [`Solid`]) which represent
+//! whole shapes (2D and 3D, respectively), while all other objects are
+//! referenced (directly or indirectly) by these top-level objects.
 //!
-//! Two objects are *equal*, if they contain the same data. For example, two
-//! instances of [`Vertex`] are equal, if they have the same position. This
-//! doesn't mean those objects are *identical*. They might have been created by
-//! different pieces of code. Or maybe by the same piece of code, but at
-//! different times, maybe even based on different inputs.
+//! All objects are stored in centralized storage (see [`Objects`]) and referred
+//! to through a [`Handle`].
+//!
+//!
+//! ## Object Equality vs Object Identity
+//!
+//! Most objects have [`Eq`]/[`PartialEq`] implementations that can be used to
+//! determine equality. Those implementations are derived, meaning two objects
+//! are equal, if all of their fields are equal. This can be used to compare
+//! objects structurally. [`Handle`]'s own [`Eq`]/[`PartialEq`] implementations
+//! defer to those of the object it references.
+//!
+//! However, that two objects are *equal* does not mean they are *identical*.
+//! See [`Handle`]'s documentation for an explanation of this distinction.
 //!
 //! This distinction is relevant, because non-identical objects that are
 //! *supposed* to be equal can end up being equal, if they are created based on
 //! simple input data (as you might have in a unit test). But they might end up
 //! slightly different, if they are created based on complex input data (as you
-//! might have in the real world).
+//! might have in the real world). This situation would most likely result in a
+//! bug that is not easily caught in testing.
 //!
-//! ## Validation Must Use Identity
+//! ### Validation Must Use Identity
 //!
 //! To prevent such situations, where everything looked fine during development,
 //! but you end up with a bug in production, any validation code that compares
 //! objects and expects them to be the same, must do that comparison based on
 //! identity, not equality. That way, this problem can never happen, because we
 //! never expect non-identical objects to be the same.
 //!
-//! ## How Identity Works
-//!
-//! We can exactly determine the identity of an object, thanks to [centralized
-//! object storage][`Objects`]. If objects are created at different times,
-//! potentially by different code, they end up being stored at different memory
-//! locations, regardless of their (non-)equality.
-//!
-//! If you have two [`Handle`]s, you can compare the identity of the objects
-//! they point to using the `id` method.
-//!
 //! [`Handle`]: crate::storage::Handle
 
 mod kinds;