WorldChange doc update (#303)

Fixes #299

Orbital/src/game/world/change/mod.rs

@@ -12,67 +12,85 @@ use crate::{
     variant::Variant,
 };
 
-use super::{Identifier, ModelUlid};
+use super::Identifier;
 
 pub mod mode;
 pub use mode::*;
 
 pub mod camera;
 pub use camera::*;
 
-/// A [WorldChange] is a _proposed change to the [World]_.  
+/// A [WorldChange] is a _proposed change_ to the [World].  
+/// Basically, whenever we need to interact with the [World], it is through
+/// a [WorldChange].
 ///
 /// [World]: super::World
 pub enum WorldChange {
-    /// Queues an [Element] to be spawned.
-    /// The given [Element] must be [Boxed](Box)!
+    /// Spawns (== adds) an [Element] to the [World].
+    ///
+    /// ⚠️ The given [Element] must be [Boxed](Box) as it's a `dyn Trait`!
+    ///
+    /// [World]: super::World
     SpawnElement(Box<dyn Element>),
-    /// Queues one or many [Element(s)](Element) to be despawned.
-    /// Use an [Identifier] to select what to despawn!
-    DespawnElement(Identifier),
-    /// Queues a [Model] to be spawned.
+    /// Despawns (== removes) one or many [Element]s from the [World].
     ///
-    /// Same as [WorldChange::SpawnModel], but without needing to supply
-    /// an [ElementUlid].
-    /// The [ElementUlid] of the current [Element] will be used.
+    /// If the identifier is used by multiple [Element]s, **all** will be
+    /// despawned.
+    ///
+    /// [World]: super::World
+    DespawnElement(Identifier),
+    /// Spawns (== add) a [Model] into the [World].
     ///
     /// [Model]: crate::resources::realizations::Model
+    /// [World]: super::World
     SpawnModel(ModelDescriptor),
-    /// Queues a [Model] to be despawned.  
-    /// Use a [ModelUlid] to specify which is being despawned.
-    ///
-    /// TODO: Update docs
+    /// Despawns (== removes) a [Model] from the [World].
     ///
     /// [Model]: crate::resources::realizations::Model
+    /// [World]: super::World
     DespawnModel(String),
-    /// Sends a message to one or many [Elements](Element).  
-    /// The message must be a [HashMap<String, Variant>].
+    /// Sends a `Message` to one or many [Element]s.
+    ///
+    /// The message must be a [HashMap<String, Variant>] and can encode most
+    /// information. Make sure to _"share information, not references"_!
+    ///
+    /// # Rejection
+    /// Will be rejected if an [Element] with the specified _Identifier_ was
+    /// not found.
+    ///
     SendMessage(Identifier, HashMap<String, Variant>),
-    /// Spawns a [Camera] with a given [CameraDescriptor].  
-    /// If the chosen `identifier` of the [Camera] is already taken, this change
-    /// will be rejected.
+    /// Spawns a [Camera] into the [World].
+    ///
+    /// # Rejection
+    /// Will be rejected if a [Camera]/[CameraDescriptor] with the specified
+    /// _Identifier_ already exists.
     ///
     /// [Camera]: crate::resources::realizations::Camera
+    /// [World]: super::World
     SpawnCamera(CameraDescriptor),
-    /// Similar to [Self::SpawnCamera], but also makes the new [Camera] active.
+    /// Does the same as [WorldChange::SpawnCamera], but also makes the new
+    /// [Camera] become active.
     ///
     /// [Camera]: crate::resources::realizations::Camera
     SpawnCameraAndMakeActive(CameraDescriptor),
-    /// Despawns a [Camera] given a `identifier` ([String]).
+    /// Despawns a [Camera] given a _Identifier_.
     ///
-    /// If a [Camera] with the given `identifier` exists, it will be removed.  
-    /// If a [Camera] with the given `identifier` does not exist, nothing will happen.
+    /// # Rejection
+    /// If a [Camera] with the given _identifier_ does not exist, the change
+    /// will be rejected.
     ///
-    /// If the active [Camera] is removed, a [Default] [Camera] will be spawned
-    /// automatically on the next cycle.
+    /// # Active [Camera] removal
+    /// If the **active** [Camera] is removed, a [Default] [Camera] will be
+    /// spawned automatically on the next cycle.
     ///
     /// [Camera]: crate::resources::realizations::Camera
     DespawnCamera(String),
     /// Changes the active [Camera] to a [Camera] with the
-    /// given `identifier` ([String]).
+    /// given _identifier_.
     ///
-    /// If a [Camera] with the given `identifier` does **not** exist,
-    /// the active [Camera] **will not be changed**.
+    /// # Rejection
+    /// If a [Camera] with the given _identifier_ does **not** exist,
+    /// the change will be rejected.
     ///
     /// [Camera]: crate::resources::realizations::Camera
     ChangeActiveCamera(String),
@@ -81,20 +99,30 @@ pub enum WorldChange {
     /// If a [Camera] exists with the specified [CameraDescriptor::identifier],
     /// any property that is set to `Some(...)` will be applied, and if the
     /// [Camera] is active, will trigger a [Buffer] update.  
+    ///
+    /// # Rejection
     /// If a [Camera] does not exists with the [CameraDescriptor::identifier],
     /// this world change will be rejected and a warning will be printed to
     /// console.
     ///
     /// [Camera]: crate::resources::realizations::Camera
     /// [Buffer]: wgpu::Buffer
     UpdateCamera(CameraChange),
-    /// Any [AppChange]s that need to be processed need to use this variant!
+    /// Passes on _any_ [AppChange]s that need to be processed
+    /// by the [AppRuntime].
+    ///
+    /// [AppRuntime]: crate::app::AppRuntime
     AppChange(AppChange),
-    /// Spawns a light into existence.
+    /// Spawns a [Light] into the [World].
+    ///
+    /// [Light]: crate::resources::realizations::Light
+    /// [World]: super::World
     SpawnLight(LightDescriptor),
-    ChangeWorldEnvironment {
-        skybox_material: MaterialDescriptor,
-    },
+    /// Changes the _World Environment_ for the [World].
+    /// This is mainly changing the _SkyBox_ and _IBL_.
+    ///
+    /// [World]: super::World
+    ChangeWorldEnvironment { skybox_material: MaterialDescriptor },
     /// Cleans the entire [World].
     /// Meaning, that any [Element]s, and their associated resources like
     /// [Model]s, will be despawned and
@@ -119,6 +147,12 @@ pub enum WorldChange {
     /// [World]: crate::game::world::World
     /// [Model]: crate::resources::realizations::Model
     CleanWorld,
+    /// Enqueues a [Loader] of any kind to the [World].
+    /// The [World] will eventually start executing the [Loader] in the
+    /// background and once done, process any [WorldChange]s proposed by it.
+    ///
+    /// [World]: super::World
+    /// [Loader]: crate::loader::Loader
     EnqueueLoader(Box<dyn Loader + Send>),
 }