Finish documenting bevy_scene (#9949)

# Objective

Finish documenting `bevy_scene`.

## Solution

Document the remaining items and add a crate-level `warn(missing_doc)`
attribute as for the other crates with completed documentation.

Author: Kanabenki

crates/bevy_scene/src/bundle.rs

@@ -24,15 +24,20 @@ pub struct SceneInstance(InstanceId);
 /// Once it's spawned, the entity will have a [`SceneInstance`] component.
 #[derive(Default, Bundle)]
 pub struct SceneBundle {
-    /// Handle to the scene to spawn
+    /// Handle to the scene to spawn.
     pub scene: Handle<Scene>,
+    /// Transform of the scene root entity.
     pub transform: Transform,
+    /// Global transform of the scene root entity.
     pub global_transform: GlobalTransform,
 
+    /// User-driven visibility of the scene root entity.
     #[cfg(feature = "bevy_render")]
     pub visibility: Visibility,
+    /// Inherited visibility of the scene root entity.
     #[cfg(feature = "bevy_render")]
     pub inherited_visibility: InheritedVisibility,
+    /// Algorithmically-computed visibility of the scene root entity for rendering.
     #[cfg(feature = "bevy_render")]
     pub view_visibility: ViewVisibility,
 }
@@ -43,15 +48,20 @@ pub struct SceneBundle {
 /// Once it's spawned, the entity will have a [`SceneInstance`] component.
 #[derive(Default, Bundle)]
 pub struct DynamicSceneBundle {
-    /// Handle to the scene to spawn
+    /// Handle to the scene to spawn.
     pub scene: Handle<DynamicScene>,
+    /// Transform of the scene root entity.
     pub transform: Transform,
+    /// Global transform of the scene root entity.
     pub global_transform: GlobalTransform,
 
+    /// User-driven visibility of the scene root entity.
     #[cfg(feature = "bevy_render")]
     pub visibility: Visibility,
+    /// Inherited visibility of the scene root entity.
     #[cfg(feature = "bevy_render")]
     pub inherited_visibility: InheritedVisibility,
+    /// Algorithmically-computed visibility of the scene root entity for rendering.
     #[cfg(feature = "bevy_render")]
     pub view_visibility: ViewVisibility,
 }

crates/bevy_scene/src/dynamic_scene.rs

@@ -26,7 +26,9 @@ use serde::Serialize;
 /// [`GlobalTransform`](bevy_transform::components::GlobalTransform) components)
 #[derive(Asset, TypePath, Default)]
 pub struct DynamicScene {
+    /// Resources stored in the dynamic scene.
     pub resources: Vec<Box<dyn Reflect>>,
+    /// Entities contained in the dynamic scene.
     pub entities: Vec<DynamicEntity>,
 }
 

crates/bevy_scene/src/lib.rs

@@ -1,4 +1,11 @@
+//! Provides scene definition, instantiation and serialization/deserialization.
+//!
+//! Scenes are collections of entities and their associated components that can be
+//! instantiated or removed from a world to allow composition. Scenes can be serialized/deserialized,
+//! for example to save part of the world state to a file.
+
 #![allow(clippy::type_complexity)]
+#![warn(missing_docs)]
 
 mod bundle;
 mod dynamic_scene;
@@ -20,6 +27,7 @@ pub use scene_filter::*;
 pub use scene_loader::*;
 pub use scene_spawner::*;
 
+#[allow(missing_docs)]
 pub mod prelude {
     #[doc(hidden)]
     pub use crate::{
@@ -31,6 +39,7 @@ pub mod prelude {
 use bevy_app::prelude::*;
 use bevy_asset::AssetApp;
 
+/// Plugin that provides scene functionality to an [`App`].
 #[derive(Default)]
 pub struct ScenePlugin;
 

crates/bevy_scene/src/scene.rs

@@ -15,10 +15,12 @@ use bevy_utils::HashMap;
 /// [`GlobalTransform`](bevy_transform::components::GlobalTransform) components)
 #[derive(Asset, TypePath, Debug)]
 pub struct Scene {
+    /// The world of the scene, containing its entities and resources.
     pub world: World,
 }
 
 impl Scene {
+    /// Creates a new scene with the given world.
     pub fn new(world: World) -> Self {
         Self { world }
     }

crates/bevy_scene/src/scene_loader.rs

@@ -9,6 +9,7 @@ use bevy_utils::BoxedFuture;
 #[cfg(feature = "serialize")]
 use serde::de::DeserializeSeed;
 
+/// [`AssetLoader`] for loading serialized Bevy scene files as [`DynamicScene`].
 #[derive(Debug)]
 pub struct SceneLoader {
     type_registry: TypeRegistryArc,

crates/bevy_scene/src/scene_spawner.rs

@@ -28,6 +28,7 @@ pub struct InstanceInfo {
     pub entity_map: HashMap<Entity, Entity>,
 }
 
+/// Unique id identifying a scene instance.
 #[derive(Copy, Clone, Debug, Eq, PartialEq, Hash)]
 pub struct InstanceId(Uuid);
 
@@ -37,6 +38,25 @@ impl InstanceId {
     }
 }
 
+/// Handles spawning and despawning scenes in the world, either synchronously or batched through the [`scene_spawner_system`].
+///
+/// Synchronous methods: (Scene operations will take effect immediately)
+/// - [`spawn_dynamic_sync`](Self::spawn_dynamic_sync)
+/// - [`spawn_sync`](Self::spawn_sync)
+/// - [`despawn_sync`](Self::despawn_sync)
+/// - [`despawn_instance_sync`](Self::despawn_instance_sync)
+/// - [`update_spawned_scenes`](Self::update_spawned_scenes)
+/// - [`spawn_queued_scenes`](Self::spawn_queued_scenes)
+/// - [`despawn_queued_scenes`](Self::despawn_queued_scenes)
+/// - [`despawn_queued_instances`](Self::despawn_queued_instances)
+///
+/// Deferred methods: (Scene operations will be processed when the [`scene_spawner_system`] is run)
+/// - [`spawn_dynamic`](Self::spawn_dynamic)
+/// - [`spawn_dynamic_as_child`](Self::spawn_dynamic_as_child)
+/// - [`spawn`](Self::spawn)
+/// - [`spawn_as_child`](Self::spawn_as_child)
+/// - [`despawn`](Self::despawn)
+/// - [`despawn_instance`](Self::despawn_instance)
 #[derive(Default, Resource)]
 pub struct SceneSpawner {
     spawned_scenes: HashMap<AssetId<Scene>, Vec<InstanceId>>,
@@ -50,27 +70,50 @@ pub struct SceneSpawner {
     scenes_with_parent: Vec<(InstanceId, Entity)>,
 }
 
+/// Errors that can occur when spawning a scene.
 #[derive(Error, Debug)]
 pub enum SceneSpawnError {
+    /// Scene contains an unregistered component type.
     #[error("scene contains the unregistered component `{type_name}`. consider adding `#[reflect(Component)]` to your type")]
-    UnregisteredComponent { type_name: String },
+    UnregisteredComponent {
+        /// Type of the unregistered component.
+        type_name: String,
+    },
+    /// Scene contains an unregistered resource type.
     #[error("scene contains the unregistered resource `{type_name}`. consider adding `#[reflect(Resource)]` to your type")]
-    UnregisteredResource { type_name: String },
+    UnregisteredResource {
+        /// Type of the unregistered resource.
+        type_name: String,
+    },
+    /// Scene contains an unregistered type.
     #[error("scene contains the unregistered type `{type_name}`. consider registering the type using `app.register_type::<T>()`")]
-    UnregisteredType { type_name: String },
+    UnregisteredType {
+        /// The unregistered type.
+        type_name: String,
+    },
+    /// Dynamic scene with the given id does not exist.
     #[error("scene does not exist")]
-    NonExistentScene { id: AssetId<DynamicScene> },
+    NonExistentScene {
+        /// Id of the non-existent dynamic scene.
+        id: AssetId<DynamicScene>,
+    },
+    /// Scene with the given id does not exist.
     #[error("scene does not exist")]
-    NonExistentRealScene { id: AssetId<Scene> },
+    NonExistentRealScene {
+        /// Id of the non-existent scene.
+        id: AssetId<Scene>,
+    },
 }
 
 impl SceneSpawner {
+    /// Schedule the spawn of a new instance of the provided dynamic scene.
     pub fn spawn_dynamic(&mut self, id: impl Into<AssetId<DynamicScene>>) -> InstanceId {
         let instance_id = InstanceId::new();
         self.dynamic_scenes_to_spawn.push((id.into(), instance_id));
         instance_id
     }
 
+    /// Schedule the spawn of a new instance of the provided dynamic scene as a child of `parent`.
     pub fn spawn_dynamic_as_child(
         &mut self,
         id: impl Into<AssetId<DynamicScene>>,
@@ -82,27 +125,32 @@ impl SceneSpawner {
         instance_id
     }
 
+    /// Schedule the spawn of a new instance of the provided scene.
     pub fn spawn(&mut self, id: impl Into<AssetId<Scene>>) -> InstanceId {
         let instance_id = InstanceId::new();
         self.scenes_to_spawn.push((id.into(), instance_id));
         instance_id
     }
 
+    /// Schedule the spawn of a new instance of the provided scene as a child of `parent`.
     pub fn spawn_as_child(&mut self, id: impl Into<AssetId<Scene>>, parent: Entity) -> InstanceId {
         let instance_id = InstanceId::new();
         self.scenes_to_spawn.push((id.into(), instance_id));
         self.scenes_with_parent.push((instance_id, parent));
         instance_id
     }
 
+    /// Schedule the despawn of all instances of the provided dynamic scene.
     pub fn despawn(&mut self, id: impl Into<AssetId<DynamicScene>>) {
         self.scenes_to_despawn.push(id.into());
     }
 
+    /// Schedule the despawn of a scene instance, removing all its entities from the world.
     pub fn despawn_instance(&mut self, instance_id: InstanceId) {
         self.instances_to_despawn.push(instance_id);
     }
 
+    /// Immediately despawns all instances of a dynamic scene.
     pub fn despawn_sync(
         &mut self,
         world: &mut World,
@@ -116,6 +164,7 @@ impl SceneSpawner {
         Ok(())
     }
 
+    /// Immediately despawns a scene instance, removing all its entities from the world.
     pub fn despawn_instance_sync(&mut self, world: &mut World, instance_id: &InstanceId) {
         if let Some(instance) = self.spawned_instances.remove(instance_id) {
             for &entity in instance.entity_map.values() {
@@ -124,6 +173,7 @@ impl SceneSpawner {
         }
     }
 
+    /// Immediately spawns a new instance of the provided dynamic scene.
     pub fn spawn_dynamic_sync(
         &mut self,
         world: &mut World,
@@ -153,6 +203,7 @@ impl SceneSpawner {
         })
     }
 
+    /// Immediately spawns a new instance of the provided scene.
     pub fn spawn_sync(
         &mut self,
         world: &mut World,
@@ -182,6 +233,9 @@ impl SceneSpawner {
         })
     }
 
+    /// Iterate through all instances of the provided scenes and update those immediately.
+    ///
+    /// Useful for updating already spawned scene instances after their corresponding scene has been modified.
     pub fn update_spawned_scenes(
         &mut self,
         world: &mut World,
@@ -199,6 +253,7 @@ impl SceneSpawner {
         Ok(())
     }
 
+    /// Immediately despawns all scenes scheduled for despawn by despawning their instances.
     pub fn despawn_queued_scenes(&mut self, world: &mut World) -> Result<(), SceneSpawnError> {
         let scenes_to_despawn = std::mem::take(&mut self.scenes_to_despawn);
 
@@ -208,6 +263,7 @@ impl SceneSpawner {
         Ok(())
     }
 
+    /// Immediately despawns all scene instances scheduled for despawn.
     pub fn despawn_queued_instances(&mut self, world: &mut World) {
         let instances_to_despawn = std::mem::take(&mut self.instances_to_despawn);
 
@@ -216,6 +272,7 @@ impl SceneSpawner {
         }
     }
 
+    /// Immediately spawns all scenes scheduled for spawn.
     pub fn spawn_queued_scenes(&mut self, world: &mut World) -> Result<(), SceneSpawnError> {
         let scenes_to_spawn = std::mem::take(&mut self.dynamic_scenes_to_spawn);
 
@@ -308,6 +365,7 @@ impl SceneSpawner {
     }
 }
 
+/// System that handles scheduled scene instance spawning and despawning through a [`SceneSpawner`].
 pub fn scene_spawner_system(world: &mut World) {
     world.resource_scope(|world, mut scene_spawner: Mut<SceneSpawner>| {
         // remove any loading instances where parent is deleted