From 4a91ecabdcac5a5f0bae256b6f11c2f0238f45a0 Mon Sep 17 00:00:00 2001 From: Hanno Braun Date: Thu, 16 Nov 2023 12:49:29 +0100 Subject: [PATCH] Properly document `operations` module --- crates/fj-core/src/operations/mod.rs | 40 +++++++++++++++++++++++++++- 1 file changed, 39 insertions(+), 1 deletion(-) diff --git a/crates/fj-core/src/operations/mod.rs b/crates/fj-core/src/operations/mod.rs index 6aaadf8da..ea218d6dd 100644 --- a/crates/fj-core/src/operations/mod.rs +++ b/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`). 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;