Update documentation of layers

crates/fj-core/src/layers/layer.rs

@@ -80,8 +80,8 @@ pub trait Command<S> {
 pub trait Event<S> {
     /// Evolve the provided state
     ///
-    /// This is the only method that gets mutable access to the state, making
-    /// sure that all changes to the state are captured as events.
+    /// This is the only method that [`Layer`] gives mutable access to the
+    /// state, making sure that all changes to the state are captured as events.
     ///
     /// Implementations of this method are supposed to be relatively dumb. Any
     /// decisions that go into updating the state should be made in

crates/fj-core/src/layers/layers.rs

@@ -21,7 +21,7 @@ use super::Layer;
 /// That can be changed, once necessary.
 #[derive(Default)]
 pub struct Layers {
-    /// The objects layers
+    /// The objects layer
     ///
     /// Manages the stores of topological and geometric objects that make up
     /// shapes.

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

@@ -8,7 +8,9 @@ use crate::{
 use super::{Command, Event, Layer};
 
 impl Layer<Objects> {
-    /// Insert and object into the stores
+    /// Insert an object into the stores
+    ///
+    /// Passes any events produced to the validation layer.
     pub fn insert(
         &mut self,
         object: AnyObject<AboutToBeStored>,
@@ -25,7 +27,8 @@ impl Layer<Objects> {
 
 /// Insert an object into the stores
 ///
-/// Event produced by `Layer<Objects>`.
+/// This struct serves as both event and command for `Layer<Objects>`, as well
+/// as a command for `Layer<Validation>`.
 #[derive(Clone, Debug)]
 pub struct InsertObject {
     /// The object to insert