From 90659d4af4d7d7bae9901c787f71c7ee9b569072 Mon Sep 17 00:00:00 2001
From: Daniel McNab <36049421+DJMcNab@users.noreply.github.com>
Date: Sun, 3 Apr 2022 20:20:03 +0100
Subject: [PATCH] Add some docs

---
 crates/bevy_render/src/extract_param.rs | 37 +++++++++++++++++++++++++
 crates/bevy_render/src/lib.rs           |  6 ++--
 2 files changed, 41 insertions(+), 2 deletions(-)

diff --git a/crates/bevy_render/src/extract_param.rs b/crates/bevy_render/src/extract_param.rs
index 75346d3fea043..95ba1333ae558 100644
--- a/crates/bevy_render/src/extract_param.rs
+++ b/crates/bevy_render/src/extract_param.rs
@@ -4,6 +4,7 @@ use bevy_ecs::{
     system::{ReadOnlySystemParamFetch, SystemParam, SystemParamItem, SystemState},
 };
 
+/// Implementation detail of [`Extract`]
 pub struct MainWorldState<P: SystemParam>(SystemState<P>);
 
 impl<P: SystemParam> FromWorld for MainWorldState<P> {
@@ -12,6 +13,42 @@ impl<P: SystemParam> FromWorld for MainWorldState<P> {
     }
 }
 
+/// A helper for accessing [`MainWorld`] content using a system parameter.
+///
+/// A [`SystemParam`] adapter which applies the contained `SystemParam` to the [`World`]
+/// contained in [`MainWorld`]. This parameter only works for systems run
+/// during [`RenderStage::Extract`].
+///
+/// This requires that the contained [`SystemParam`] does not mutate the world, as it
+/// uses [`Res<MainWorld>`](Res). To get access to the contained `SystemParam`'s item, you
+/// must use [`Extract::value`]. This is required because of lifetime limitations in
+/// the `SystemParam` api.
+///
+/// ## Context
+///
+/// [`RenderStage::Extract`] is used to extract (move) data from the simulation world ([`MainWorld`]) to the
+/// render world. The render world drives rendering each frame (generally to a [Window]).
+/// This design is used to allow performing calculations related to rendering a prior frame at the same
+/// time as the next frame is simulated, which increases throughput (FPS).
+///
+/// [`Extract`] is used to get data from the main world during [`RenderStage::Extract`].
+///
+/// ## Examples
+///
+/// ```rust
+/// use bevy_ecs::prelude::*;
+/// use bevy_render::Extract;
+/// # #[derive(Component)]
+/// # struct Cloud;
+/// fn extract_clouds(mut commands: Commands, mut clouds: Extract<Query<Entity, With<Cloud>>>) {
+///     for cloud in clouds.value().iter() {
+///         commands.get_or_spawn(cloud).insert(Cloud);
+///     }
+/// }
+/// ```
+///
+/// [`RenderStage::Extract`]: crate::RenderStage::Extract
+/// [Window]: bevy_window::Window
 #[derive(SystemParam)]
 pub struct Extract<'w, 's, P: SystemParam + 'static>
 where
diff --git a/crates/bevy_render/src/lib.rs b/crates/bevy_render/src/lib.rs
index 418a6b06848e7..744ac8aa022d9 100644
--- a/crates/bevy_render/src/lib.rs
+++ b/crates/bevy_render/src/lib.rs
@@ -81,7 +81,9 @@ pub enum RenderStage {
     Cleanup,
 }
 
-/// The Render App World. This is only available as a resource during the Extract step.
+/// The simulation [World] of the application, stored as a resource.
+/// This resource is only available during [`RenderStage::Extract`].
+/// See [`Extract`] for more details.
 #[derive(Default)]
 pub struct MainWorld(World);
 
@@ -110,7 +112,7 @@ pub mod main_graph {
 pub struct RenderApp;
 
 /// A "scratch" world used to avoid allocating new worlds every frame when
-/// swapping out the [`RenderWorld`].
+/// swapping out the [`MainWorld`] for [`RenderStage::Extract`].
 #[derive(Default)]
 struct ScratchMainWorld(World);