Properly document operations module

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

@@ -1,4 +1,42 @@
-//! Operations to update shapes
+//! # Create and modify shapes
+//!
+//! ## Purpose and Design
+//!
+//! This module provides functionality to create and modify shapes, generally in
+//! the form of extension traits. These extension traits are implemented for the
+//! object types that the functionality applies to, making them easily available
+//! to the caller, without creating a huge, monolithic API that would clutter up
+//! the modules that those object types are defined in.
+//!
+//! Objects are immutable, so to update one, one must create a new version of
+//! the object that incorporates the update. For this reason, the extension
+//! traits generally take `&self` and return the newly created object. Trait
+//! methods are annotated with `#[must_use]`, to prevent mistakes due to
+//! misunderstanding this principle.
+//!
+//!
+//! ### Bare Objects vs `Handle`
+//!
+//! Extension traits are mostly implemented for bare object types (i.e. for
+//! `Vertex` instead of `Handle<Vertex>`). This makes those operations more
+//! flexible, as a `Handle` might not be available, but a bare object can always
+//! be produced from a `Handle`.
+//!
+//! They also mostly return bare objects, which also provides more flexibility
+//! to the user. An inserted object must always be valid, but in a series of
+//! operations, any intermediate ones might leave the object in an invalid
+//! state. By returning the bare object, the decision when to insert the object
+//! is left to the caller.
+//!
+//! Some operations might deviate from this rule, where it makes sense.
+//!
+//!
+//! ## Implementation Note
+//!
+//! Not all operation methods take `&self`, and not all are implemented for bare
+//! objects first. Where this is done without a clear justification, you can
+//! assume that the code in question is outdated. Feel free to open an issue or
+//! send a pull request!
 
 pub mod build;
 pub mod insert;