From ab2b895693088b2f75fe01f6e4c27b0ee4e4197b Mon Sep 17 00:00:00 2001
From: Mark Schmale <masch@masch.it>
Date: Sat, 19 Mar 2022 11:32:43 +0100
Subject: [PATCH 01/23] Add a module doc block to the `2d/contributors`
 example.

The comment aims to explain what the example shows and to give an overview on how it works.
---
 examples/games/contributors.rs | 29 +++++++++++++++++++++++++++++
 1 file changed, 29 insertions(+)

diff --git a/examples/games/contributors.rs b/examples/games/contributors.rs
index 7cc038e06a728..a2d69ffa7ebc1 100644
--- a/examples/games/contributors.rs
+++ b/examples/games/contributors.rs
@@ -1,3 +1,32 @@
+//! This example collects a list of all contributors to the bevy source code and renders a bouncing
+//! bevy logo for each of them, showing how to combine multiple systems to
+//! - load some external information on startup
+//! - animate 2d sprites with some basic collision detection and physics simulation
+//! - uses a [`Timer`] to periodically highlight different logos
+//! - displays the highlighted contributors name using the [`TextBundle`] from [`bevy::ui`].
+//!
+//! This is broken down into distinct, simple systems that build upon each other.
+//! The `setup_contributor_selection` system generates a list of contributors, generates a
+//! random starting position, `Velocity` and color for each of them, and spawns one entity for
+//! each contributor into the world, consisting of a [`SpriteBundle`] for rendering the logo,
+//! the initial choose `Velocity` as well as the colour.
+//!
+//! The `setup` system then sets up the [`OrthographicCamera`](OrthographicCameraBundle) for 2D
+//! rendering, the [`UiCamera`](UiCameraBundle) for rendering the text, and the [`TextBundle`] to
+//! display the contributor name.
+//!
+//! The `velocity_system` applies some simple gravity simulation to the velocity of entities.
+//!
+//! The `move_system` system then uses that velocity to update the sprites position, based on the
+//! time that has passed since the last update.
+//!
+//! The `collision_system` system makes sure all bouncing logos stay inside the viewport by checking
+//! for collisions with the four edges, and updating the velocity.
+//!
+//! At last, the `select` system checks if the `SelectTimer` has expired and if it has, updates
+//! the contributor text, resets the color of the currently highlighted sprite, and highlights the
+//! next one.
+
 use bevy::{prelude::*, utils::HashSet};
 use rand::{prelude::SliceRandom, Rng};
 use std::{

From 9f6925d49f63a24a648469a968ead4707c893415 Mon Sep 17 00:00:00 2001
From: Mark Schmale <masch@masch.it>
Date: Sat, 19 Mar 2022 11:55:49 +0100
Subject: [PATCH 02/23] Add a module doc block to the `2d/many_sprites`
 benchmark example.

---
 examples/stress_tests/many_sprites.rs | 15 +++++++++++++--
 1 file changed, 13 insertions(+), 2 deletions(-)

diff --git a/examples/stress_tests/many_sprites.rs b/examples/stress_tests/many_sprites.rs
index ede9934aa3f89..f71cf43db4b6a 100644
--- a/examples/stress_tests/many_sprites.rs
+++ b/examples/stress_tests/many_sprites.rs
@@ -1,3 +1,16 @@
+//! Renders a lot of sprites to allow performance testing.
+//! See <https://github.com/bevyengine/bevy/pull/1492>
+//!
+//! It sets up many sprites in different sizes and rotations, and at different scales in the world,
+//! and moves the camera over them to see how well frustum culling works.
+//!
+//! Since its a kind of benchmark, it also uses the [`LogDiagnosticsPlugin`] and the
+//! [`FrameTimeDiagnosticsPlugin`] to display performance statistics in the console.
+//!
+//! It also displays on how to use a [`Local`] system parameter in `print_sprite_count`, where that
+//! system is the only one able to access this value, in this case, the [`Timer`] used to determine
+//! when to print the sprite count.
+
 use bevy::{
     diagnostic::{FrameTimeDiagnosticsPlugin, LogDiagnosticsPlugin},
     math::Quat,
@@ -9,8 +22,6 @@ use rand::Rng;
 
 const CAMERA_SPEED: f32 = 1000.0;
 
-/// This example is for performance testing purposes.
-/// See <https://github.com/bevyengine/bevy/pull/1492>
 fn main() {
     App::new()
         .add_plugin(LogDiagnosticsPlugin::default())

From c55dbf9ae228f7bd3d0f4e999ec4a1ee22c6cdff Mon Sep 17 00:00:00 2001
From: Mark Schmale <masch@masch.it>
Date: Sat, 19 Mar 2022 12:12:19 +0100
Subject: [PATCH 03/23] Add a very brief module doc block to the `2d/mesh2d`
 example.

---
 examples/2d/mesh2d.rs | 2 ++
 1 file changed, 2 insertions(+)

diff --git a/examples/2d/mesh2d.rs b/examples/2d/mesh2d.rs
index 8b968a3966892..6412c97f88b68 100644
--- a/examples/2d/mesh2d.rs
+++ b/examples/2d/mesh2d.rs
@@ -1,3 +1,5 @@
+//! Shows how to render a polygonal [`Mesh`], generated from a [`Quad`] primitive, in a 2D scene.
+
 use bevy::{prelude::*, sprite::MaterialMesh2dBundle};
 
 fn main() {

From c22897115f100a63b7884b85fe2e4a52c94a52c9 Mon Sep 17 00:00:00 2001
From: Mark Schmale <masch@masch.it>
Date: Sat, 19 Mar 2022 12:13:04 +0100
Subject: [PATCH 04/23] Move the doc block for `2d/mesh2d_manual` from the main
 function, to the module level.

---
 examples/2d/mesh2d_manual.rs | 8 +++++---
 1 file changed, 5 insertions(+), 3 deletions(-)

diff --git a/examples/2d/mesh2d_manual.rs b/examples/2d/mesh2d_manual.rs
index e585018aa5448..c6367b1abebe4 100644
--- a/examples/2d/mesh2d_manual.rs
+++ b/examples/2d/mesh2d_manual.rs
@@ -1,3 +1,8 @@
+//! This example shows how to manually render 2d items using "mid level render apis" with  a custom
+//! pipeline for 2d meshes.
+//! It doesn't use the [`Material2d`] abstraction, but changes the vertex buffer to include vertex color
+//! Check out the "mesh2d" example for simpler / higher level 2d meshes
+
 use bevy::{
     core_pipeline::Transparent2d,
     prelude::*,
@@ -23,9 +28,6 @@ use bevy::{
     utils::FloatOrd,
 };
 
-/// This example shows how to manually render 2d items using "mid level render apis" with a custom pipeline for 2d meshes
-/// It doesn't use the [`Material2d`] abstraction, but changes the vertex buffer to include vertex color
-/// Check out the "mesh2d" example for simpler / higher level 2d meshes
 fn main() {
     App::new()
         .add_plugins(DefaultPlugins)

From f2225ec3157f26ade8b30dcdd397e3366d710638 Mon Sep 17 00:00:00 2001
From: Mark Schmale <masch@masch.it>
Date: Sat, 19 Mar 2022 12:43:06 +0100
Subject: [PATCH 05/23] Add a module doc block to the `2d/move_sprite` example.

---
 examples/2d/move_sprite.rs | 8 ++++++++
 1 file changed, 8 insertions(+)

diff --git a/examples/2d/move_sprite.rs b/examples/2d/move_sprite.rs
index a895212b3ae51..c91dbfcc59b12 100644
--- a/examples/2d/move_sprite.rs
+++ b/examples/2d/move_sprite.rs
@@ -1,3 +1,11 @@
+//! Renders a single, moving sprite in a 2D scene.
+//!
+//! The `setup` systems creates the 2D camera by spawning a [`OrthographicCameraBundle`], and the
+//! entity in form of a [`SpriteBundle`], loading an image via the [`AssetServer`].
+//!
+//! The `movement_system` then animates the sprite moving up and down, changing direction when the
+//! y offset reaches a threshold.
+
 use bevy::prelude::*;
 
 fn main() {

From 1fcbfb9e5036dde005de51b1f86dd06a4df5e3d1 Mon Sep 17 00:00:00 2001
From: Mark Schmale <masch@masch.it>
Date: Sat, 19 Mar 2022 12:43:13 +0100
Subject: [PATCH 06/23] Add a module doc block to the `2d/rect` example.

---
 examples/2d/sprite.rs | 5 +++++
 1 file changed, 5 insertions(+)

diff --git a/examples/2d/sprite.rs b/examples/2d/sprite.rs
index 6620aa9619035..452710e095adc 100644
--- a/examples/2d/sprite.rs
+++ b/examples/2d/sprite.rs
@@ -1,3 +1,8 @@
+//! Shows how to render simple rectangle sprite with a single color.
+//!
+//! Since this [`Sprite`] is not generated from an image, we have create it directly when spawning
+//! the [`SpriteBundle`] and specify the size using `custom_size`.
+
 use bevy::prelude::*;
 
 fn main() {

From eef3fdb65a696840e8d30b0018401b31b4548c40 Mon Sep 17 00:00:00 2001
From: Mark Schmale <masch@masch.it>
Date: Thu, 7 Apr 2022 10:03:04 +0200
Subject: [PATCH 07/23] Add a simple module doc block to the `2d/sprite`
 example.

---
 examples/2d/sprite.rs | 5 +----
 1 file changed, 1 insertion(+), 4 deletions(-)

diff --git a/examples/2d/sprite.rs b/examples/2d/sprite.rs
index 452710e095adc..6ebe25dc19c95 100644
--- a/examples/2d/sprite.rs
+++ b/examples/2d/sprite.rs
@@ -1,7 +1,4 @@
-//! Shows how to render simple rectangle sprite with a single color.
-//!
-//! Since this [`Sprite`] is not generated from an image, we have create it directly when spawning
-//! the [`SpriteBundle`] and specify the size using `custom_size`.
+//! Displays a single [`Sprite`], created from an image.
 
 use bevy::prelude::*;
 

From b8c681715060803dab3921ab565e58487fa32211 Mon Sep 17 00:00:00 2001
From: Mark Schmale <masch@masch.it>
Date: Thu, 7 Apr 2022 10:03:17 +0200
Subject: [PATCH 08/23] Add a simple module doc block to the
 `2d/sprite_flipping` example.

---
 examples/2d/sprite_flipping.rs | 2 ++
 1 file changed, 2 insertions(+)

diff --git a/examples/2d/sprite_flipping.rs b/examples/2d/sprite_flipping.rs
index e89968cf962e6..761741572086e 100644
--- a/examples/2d/sprite_flipping.rs
+++ b/examples/2d/sprite_flipping.rs
@@ -1,3 +1,5 @@
+//! Displays a single [`Sprite`], created from an image, but flipped on one axis.
+
 use bevy::prelude::*;
 
 fn main() {

From 1c5c560e7f126835a83ba06b98aa15e70e34ead8 Mon Sep 17 00:00:00 2001
From: Mark Schmale <masch@masch.it>
Date: Thu, 7 Apr 2022 10:06:17 +0200
Subject: [PATCH 09/23] moved the comment from main to the file head

---
 examples/2d/texture_atlas.rs | 5 +++--
 1 file changed, 3 insertions(+), 2 deletions(-)

diff --git a/examples/2d/texture_atlas.rs b/examples/2d/texture_atlas.rs
index 8aa7bcae4329a..cde80e51ec2e8 100644
--- a/examples/2d/texture_atlas.rs
+++ b/examples/2d/texture_atlas.rs
@@ -1,7 +1,8 @@
+//! In this example we generate a new texture atlas (sprite sheet) from a folder containing
+//! individual sprites
+
 use bevy::{asset::LoadState, prelude::*};
 
-/// In this example we generate a new texture atlas (sprite sheet) from a folder containing
-/// individual sprites
 fn main() {
     App::new()
         .init_resource::<RpgSpriteHandles>()

From c2e78cf8e56c7e99fafb973acd565be6324ab7a2 Mon Sep 17 00:00:00 2001
From: Mark Schmale <masch@masch.it>
Date: Thu, 7 Apr 2022 10:06:42 +0200
Subject: [PATCH 10/23] Add a module doc block to the `2d/text2d` example.

---
 examples/2d/text2d.rs | 8 ++++++++
 1 file changed, 8 insertions(+)

diff --git a/examples/2d/text2d.rs b/examples/2d/text2d.rs
index e346cee7242e5..f7b1b746cad86 100644
--- a/examples/2d/text2d.rs
+++ b/examples/2d/text2d.rs
@@ -1,3 +1,11 @@
+//! Example to show text rendering with moving, rotating and scaling text.
+//!
+//! Note that this uses [`Text2dBundle`] to display text using the same [`OrthographicCameraBundle`]
+//! that also would show your sprites, instead of the [`TextBundle`] which requires a [`UiCameraBundle`]
+//! to be displayed.
+//! For an example on how to render text as part of a user interface, independent from the world
+//! viewport, you may want to look at `2d/contributors.rs` or `ui/text.rs`.
+
 use bevy::{prelude::*, text::Text2dBounds};
 
 fn main() {

From 9c0c7b1cd0e2c2da692525b5be80177c2d584b25 Mon Sep 17 00:00:00 2001
From: Mark Schmale <masch@masch.it>
Date: Fri, 8 Apr 2022 13:11:46 +0200
Subject: [PATCH 11/23] Cut the long comments, reworded others.

The plan here is having a short, but helpful, introduction to each example. Stating what is meant to be shown, without going into details.
---
 examples/2d/move_sprite.rs            | 10 +++------
 examples/2d/rotation.rs               |  2 ++
 examples/2d/sprite_sheet.rs           |  3 +++
 examples/2d/text2d.rs                 |  5 ++---
 examples/games/contributors.rs        | 29 +--------------------------
 examples/stress_tests/many_sprites.rs |  8 +-------
 6 files changed, 12 insertions(+), 45 deletions(-)

diff --git a/examples/2d/move_sprite.rs b/examples/2d/move_sprite.rs
index c91dbfcc59b12..856adcd31bea7 100644
--- a/examples/2d/move_sprite.rs
+++ b/examples/2d/move_sprite.rs
@@ -1,10 +1,4 @@
-//! Renders a single, moving sprite in a 2D scene.
-//!
-//! The `setup` systems creates the 2D camera by spawning a [`OrthographicCameraBundle`], and the
-//! entity in form of a [`SpriteBundle`], loading an image via the [`AssetServer`].
-//!
-//! The `movement_system` then animates the sprite moving up and down, changing direction when the
-//! y offset reaches a threshold.
+//! Renders a 2D scene containing a single, moving sprite.
 
 use bevy::prelude::*;
 
@@ -33,6 +27,8 @@ fn setup(mut commands: Commands, asset_server: Res<AssetServer>) {
         .insert(Direction::Up);
 }
 
+/// The sprite is animated by changing its translation depending on the time that has passed since
+/// the last frame.
 fn sprite_movement(time: Res<Time>, mut sprite_position: Query<(&mut Direction, &mut Transform)>) {
     for (mut logo, mut transform) in sprite_position.iter_mut() {
         match *logo {
diff --git a/examples/2d/rotation.rs b/examples/2d/rotation.rs
index 1eeab613cb034..46189fc5b639c 100644
--- a/examples/2d/rotation.rs
+++ b/examples/2d/rotation.rs
@@ -1,3 +1,5 @@
+//! Demonstrates rotating entities in 2D with quaternions.
+
 use bevy::{
     core::FixedTimestep,
     math::{const_vec2, Vec3Swizzles},
diff --git a/examples/2d/sprite_sheet.rs b/examples/2d/sprite_sheet.rs
index d3d313fab226e..59970231f3821 100644
--- a/examples/2d/sprite_sheet.rs
+++ b/examples/2d/sprite_sheet.rs
@@ -1,3 +1,6 @@
+//! Renders an animated sprite by loading all animation frames from a single image (a sprite sheet)
+//! into a texture atlas, and changing the displayed image periodically.
+
 use bevy::prelude::*;
 
 fn main() {
diff --git a/examples/2d/text2d.rs b/examples/2d/text2d.rs
index f7b1b746cad86..b43b627155379 100644
--- a/examples/2d/text2d.rs
+++ b/examples/2d/text2d.rs
@@ -1,8 +1,7 @@
 //! Example to show text rendering with moving, rotating and scaling text.
 //!
-//! Note that this uses [`Text2dBundle`] to display text using the same [`OrthographicCameraBundle`]
-//! that also would show your sprites, instead of the [`TextBundle`] which requires a [`UiCameraBundle`]
-//! to be displayed.
+//! Note that this uses [`Text2dBundle`] to display text alongside your other entities in a 2D scene.
+//!
 //! For an example on how to render text as part of a user interface, independent from the world
 //! viewport, you may want to look at `2d/contributors.rs` or `ui/text.rs`.
 
diff --git a/examples/games/contributors.rs b/examples/games/contributors.rs
index a2d69ffa7ebc1..e0b5f4f5dc034 100644
--- a/examples/games/contributors.rs
+++ b/examples/games/contributors.rs
@@ -1,31 +1,4 @@
-//! This example collects a list of all contributors to the bevy source code and renders a bouncing
-//! bevy logo for each of them, showing how to combine multiple systems to
-//! - load some external information on startup
-//! - animate 2d sprites with some basic collision detection and physics simulation
-//! - uses a [`Timer`] to periodically highlight different logos
-//! - displays the highlighted contributors name using the [`TextBundle`] from [`bevy::ui`].
-//!
-//! This is broken down into distinct, simple systems that build upon each other.
-//! The `setup_contributor_selection` system generates a list of contributors, generates a
-//! random starting position, `Velocity` and color for each of them, and spawns one entity for
-//! each contributor into the world, consisting of a [`SpriteBundle`] for rendering the logo,
-//! the initial choose `Velocity` as well as the colour.
-//!
-//! The `setup` system then sets up the [`OrthographicCamera`](OrthographicCameraBundle) for 2D
-//! rendering, the [`UiCamera`](UiCameraBundle) for rendering the text, and the [`TextBundle`] to
-//! display the contributor name.
-//!
-//! The `velocity_system` applies some simple gravity simulation to the velocity of entities.
-//!
-//! The `move_system` system then uses that velocity to update the sprites position, based on the
-//! time that has passed since the last update.
-//!
-//! The `collision_system` system makes sure all bouncing logos stay inside the viewport by checking
-//! for collisions with the four edges, and updating the velocity.
-//!
-//! At last, the `select` system checks if the `SelectTimer` has expired and if it has, updates
-//! the contributor text, resets the color of the currently highlighted sprite, and highlights the
-//! next one.
+//! This example displays each contributor to the bevy source code as a bouncing bevy-ball.
 
 use bevy::{prelude::*, utils::HashSet};
 use rand::{prelude::SliceRandom, Rng};
diff --git a/examples/stress_tests/many_sprites.rs b/examples/stress_tests/many_sprites.rs
index f71cf43db4b6a..8ef12d9ae58bc 100644
--- a/examples/stress_tests/many_sprites.rs
+++ b/examples/stress_tests/many_sprites.rs
@@ -3,13 +3,6 @@
 //!
 //! It sets up many sprites in different sizes and rotations, and at different scales in the world,
 //! and moves the camera over them to see how well frustum culling works.
-//!
-//! Since its a kind of benchmark, it also uses the [`LogDiagnosticsPlugin`] and the
-//! [`FrameTimeDiagnosticsPlugin`] to display performance statistics in the console.
-//!
-//! It also displays on how to use a [`Local`] system parameter in `print_sprite_count`, where that
-//! system is the only one able to access this value, in this case, the [`Timer`] used to determine
-//! when to print the sprite count.
 
 use bevy::{
     diagnostic::{FrameTimeDiagnosticsPlugin, LogDiagnosticsPlugin},
@@ -24,6 +17,7 @@ const CAMERA_SPEED: f32 = 1000.0;
 
 fn main() {
     App::new()
+        // Since this is also used as a benchmark, we want it to display performance data.
         .add_plugin(LogDiagnosticsPlugin::default())
         .add_plugin(FrameTimeDiagnosticsPlugin::default())
         .add_plugins(DefaultPlugins)

From 301d75b7cf6264baaa355ad73f9c89c43101bf5e Mon Sep 17 00:00:00 2001
From: Mark Schmale <masch@masch.it>
Date: Sun, 17 Apr 2022 13:24:38 +0200
Subject: [PATCH 12/23] Add missing module doc blocks to examples.

I used the text from the README as a default, or comments from the `main` if they existed in the example, sometime adding a bit more context.
Some slight re-wording or layout changes where also applied.
---
 examples/3d/3d_scene.rs                       |  2 +
 examples/3d/lighting.rs                       |  2 +
 examples/3d/load_gltf.rs                      |  2 +
 examples/3d/msaa.rs                           | 15 +++---
 examples/3d/orthographic.rs                   |  2 +
 examples/3d/parenting.rs                      |  5 +-
 examples/3d/pbr.rs                            |  3 +-
 examples/3d/render_to_texture.rs              |  2 +
 examples/3d/shadow_biases.rs                  |  2 +
 examples/3d/shadow_caster_receiver.rs         |  2 +
 examples/3d/spherical_area_lights.rs          |  2 +
 examples/3d/texture.rs                        |  3 +-
 examples/3d/update_gltf_scene.rs              |  3 ++
 examples/3d/wireframe.rs                      |  2 +
 examples/animation/animated_fox.rs            |  2 +
 examples/animation/custom_skinned_mesh.rs     |  5 +-
 examples/animation/gltf_skinned_mesh.rs       |  7 +--
 examples/app/custom_loop.rs                   |  5 +-
 examples/app/drag_and_drop.rs                 |  2 +
 examples/app/empty.rs                         |  2 +
 examples/app/empty_defaults.rs                |  2 +
 examples/app/headless.rs                      | 16 +++---
 examples/app/headless_defaults.rs             |  2 +
 examples/app/logs.rs                          |  2 +-
 examples/app/plugin.rs                        |  9 ++--
 examples/app/plugin_group.rs                  |  4 +-
 examples/app/return_after_run.rs              |  2 +
 examples/app/thread_pool_resources.rs         |  5 +-
 examples/app/without_winit.rs                 |  2 +
 examples/asset/asset_loading.rs               |  3 +-
 examples/asset/custom_asset.rs                |  2 +
 examples/asset/custom_asset_io.rs             |  6 ++-
 examples/asset/hot_asset_reloading.rs         |  7 +--
 examples/async_tasks/async_compute.rs         |  5 +-
 .../external_source_external_thread.rs        |  2 +
 examples/audio/audio.rs                       |  3 +-
 examples/audio/audio_control.rs               |  3 +-
 examples/diagnostics/custom_diagnostic.rs     |  3 +-
 examples/diagnostics/log_diagnostics.rs       |  2 +
 examples/ecs/component_change_detection.rs    |  3 +-
 examples/ecs/custom_query_param.rs            | 27 +++++-----
 examples/ecs/ecs_guide.rs                     | 52 +++++++++----------
 examples/ecs/event.rs                         |  5 +-
 examples/ecs/fixed_timestep.rs                |  2 +
 examples/ecs/generic_system.rs                | 22 ++++----
 examples/ecs/hierarchy.rs                     |  2 +
 examples/ecs/iter_combinations.rs             |  2 +
 examples/ecs/parallel_query.rs                |  2 +
 examples/ecs/removal_detection.rs             |  2 +-
 examples/ecs/startup_system.rs                |  2 +
 examples/ecs/state.rs                         |  5 +-
 examples/ecs/system_chaining.rs               |  2 +
 examples/ecs/system_param.rs                  |  3 +-
 examples/ecs/system_sets.rs                   | 45 ++++++++--------
 examples/ecs/timers.rs                        |  2 +
 examples/games/alien_cake_addict.rs           |  8 +--
 examples/games/game_menu.rs                   |  8 +--
 examples/input/char_input_events.rs           |  2 +
 examples/input/gamepad_input.rs               |  2 +
 examples/input/gamepad_input_events.rs        |  2 +
 examples/input/keyboard_input.rs              |  2 +
 examples/input/keyboard_input_events.rs       |  2 +
 examples/input/keyboard_modifiers.rs          |  2 +
 examples/input/mouse_grab.rs                  |  2 +
 examples/input/mouse_input.rs                 |  2 +
 examples/input/mouse_input_events.rs          |  2 +
 examples/input/touch_input.rs                 |  2 +
 examples/input/touch_input_events.rs          |  2 +
 examples/reflection/generic_reflection.rs     |  4 +-
 examples/reflection/reflection.rs             |  8 +--
 examples/reflection/reflection_types.rs       |  3 +-
 examples/reflection/trait_reflection.rs       |  2 +
 examples/scene/scene.rs                       |  3 +-
 examples/shader/animate_shader.rs             |  6 ++-
 .../shader/compute_shader_game_of_life.rs     |  7 ++-
 examples/shader/custom_vertex_attribute.rs    |  2 +
 examples/shader/shader_defs.rs                |  3 ++
 examples/shader/shader_instancing.rs          |  4 ++
 examples/shader/shader_material.rs            |  2 +
 examples/shader/shader_material_glsl.rs       |  2 +
 .../shader_material_screenspace_texture.rs    |  2 +
 examples/stress_tests/bevymark.rs             |  7 +--
 examples/stress_tests/many_cubes.rs           | 14 +++++
 examples/tools/scene_viewer.rs                |  6 +++
 examples/transforms/3d_rotation.rs            |  2 +
 .../transforms/global_vs_local_translation.rs | 12 +++--
 examples/transforms/scale.rs                  |  2 +
 examples/transforms/transform.rs              |  2 +
 examples/transforms/translation.rs            |  2 +
 examples/ui/button.rs                         |  5 +-
 examples/ui/font_atlas_debug.rs               |  6 +--
 examples/ui/text.rs                           |  7 +--
 examples/ui/text_debug.rs                     |  3 +-
 examples/ui/ui.rs                             |  3 +-
 examples/window/clear_color.rs                |  2 +
 examples/window/low_power.rs                  |  7 +--
 examples/window/multiple_windows.rs           |  3 +-
 examples/window/scale_factor_override.rs      |  3 +-
 examples/window/transparent_window.rs         |  5 +-
 examples/window/window_settings.rs            |  3 +-
 100 files changed, 345 insertions(+), 163 deletions(-)

diff --git a/examples/3d/3d_scene.rs b/examples/3d/3d_scene.rs
index 6f2a311714c7a..b24993d9849ae 100644
--- a/examples/3d/3d_scene.rs
+++ b/examples/3d/3d_scene.rs
@@ -1,3 +1,5 @@
+//! Simple 3D scene with basic shapes and lighting
+
 use bevy::prelude::*;
 
 fn main() {
diff --git a/examples/3d/lighting.rs b/examples/3d/lighting.rs
index 7feb35250c69b..2e00bb4307f74 100644
--- a/examples/3d/lighting.rs
+++ b/examples/3d/lighting.rs
@@ -1,3 +1,5 @@
+//! Illustrates various lighting options in a simple scene
+
 use bevy::prelude::*;
 
 fn main() {
diff --git a/examples/3d/load_gltf.rs b/examples/3d/load_gltf.rs
index c309852251982..683ba3bd3d461 100644
--- a/examples/3d/load_gltf.rs
+++ b/examples/3d/load_gltf.rs
@@ -1,3 +1,5 @@
+//! Loads and renders a gltf file as a scene
+
 use bevy::prelude::*;
 
 fn main() {
diff --git a/examples/3d/msaa.rs b/examples/3d/msaa.rs
index 8719658577026..d7f8534da3edb 100644
--- a/examples/3d/msaa.rs
+++ b/examples/3d/msaa.rs
@@ -1,12 +1,13 @@
+//! This example shows how to configure Multi-Sample Anti-Aliasing. Setting the sample count higher
+//! will result in smoother edges, but it will also increase the cost to render those edges. The
+//! range should generally be somewhere between 1 (no multi sampling, but cheap) to 8 (crisp but
+//! expensive).
+//! Note that WGPU currently only supports 1 or 4 samples.
+//! Ultimately we plan on supporting whatever is natively supported on a given device.
+//! Check out [this issue](https://github.com/gfx-rs/wgpu/issues/1832) for more info.
+
 use bevy::prelude::*;
 
-/// This example shows how to configure Multi-Sample Anti-Aliasing. Setting the sample count higher
-/// will result in smoother edges, but it will also increase the cost to render those edges. The
-/// range should generally be somewhere between 1 (no multi sampling, but cheap) to 8 (crisp but
-/// expensive).
-/// Note that WGPU currently only supports 1 or 4 samples.
-/// Ultimately we plan on supporting whatever is natively supported on a given device.
-/// Check out [this issue](https://github.com/gfx-rs/wgpu/issues/1832) for more info.
 fn main() {
     App::new()
         .insert_resource(Msaa { samples: 4 })
diff --git a/examples/3d/orthographic.rs b/examples/3d/orthographic.rs
index 5eeddcfda1c7f..fbf560e9bee9c 100644
--- a/examples/3d/orthographic.rs
+++ b/examples/3d/orthographic.rs
@@ -1,3 +1,5 @@
+//! Shows how to create a 3D orthographic view (for isometric-look games or CAD applications)
+
 use bevy::prelude::*;
 
 fn main() {
diff --git a/examples/3d/parenting.rs b/examples/3d/parenting.rs
index 8601e98f616b1..9a46112d981f6 100644
--- a/examples/3d/parenting.rs
+++ b/examples/3d/parenting.rs
@@ -1,7 +1,8 @@
+//! This example illustrates how to create parent->child relationships between entities how parent
+//! transforms are propagated to their descendants
+
 use bevy::prelude::*;
 
-/// This example illustrates how to create parent->child relationships between entities how parent
-/// transforms are propagated to their descendants
 fn main() {
     App::new()
         .insert_resource(Msaa { samples: 4 })
diff --git a/examples/3d/pbr.rs b/examples/3d/pbr.rs
index 0565e18693882..7a5a6bd7b490c 100644
--- a/examples/3d/pbr.rs
+++ b/examples/3d/pbr.rs
@@ -1,6 +1,7 @@
+//! This example shows how to configure Physically Based Rendering (PBR) parameters.
+
 use bevy::prelude::*;
 
-/// This example shows how to configure Physically Based Rendering (PBR) parameters.
 fn main() {
     App::new()
         .add_plugins(DefaultPlugins)
diff --git a/examples/3d/render_to_texture.rs b/examples/3d/render_to_texture.rs
index fb27722342d46..505cdf1fac80f 100644
--- a/examples/3d/render_to_texture.rs
+++ b/examples/3d/render_to_texture.rs
@@ -1,3 +1,5 @@
+//! Shows how to render to a texture, useful for mirrors, UI, or exporting images
+
 use bevy::{
     core_pipeline::{
         draw_3d_graph, node, AlphaMask3d, Opaque3d, RenderTargetClearColors, Transparent3d,
diff --git a/examples/3d/shadow_biases.rs b/examples/3d/shadow_biases.rs
index 12516debe565c..4954a3131ecbb 100644
--- a/examples/3d/shadow_biases.rs
+++ b/examples/3d/shadow_biases.rs
@@ -1,3 +1,5 @@
+//! Demonstrates how shadow biases affect shadows in a 3d scene
+
 use bevy::{input::mouse::MouseMotion, prelude::*};
 
 fn main() {
diff --git a/examples/3d/shadow_caster_receiver.rs b/examples/3d/shadow_caster_receiver.rs
index fb93f62ab3757..7921554a7290c 100644
--- a/examples/3d/shadow_caster_receiver.rs
+++ b/examples/3d/shadow_caster_receiver.rs
@@ -1,3 +1,5 @@
+//! Demonstrates how to prevent meshes from casting/receiving shadows in a 3d scene
+
 use bevy::{
     pbr::{NotShadowCaster, NotShadowReceiver},
     prelude::*,
diff --git a/examples/3d/spherical_area_lights.rs b/examples/3d/spherical_area_lights.rs
index 8347789e690ec..a5f84a4e4921e 100644
--- a/examples/3d/spherical_area_lights.rs
+++ b/examples/3d/spherical_area_lights.rs
@@ -1,3 +1,5 @@
+//! Demonstrates how point light radius values affect light behavior.
+
 use bevy::prelude::*;
 
 fn main() {
diff --git a/examples/3d/texture.rs b/examples/3d/texture.rs
index 7ee3384addbf5..13368dd2dd522 100644
--- a/examples/3d/texture.rs
+++ b/examples/3d/texture.rs
@@ -1,6 +1,7 @@
+//! This example shows various ways to configure texture materials in 3D
+
 use bevy::prelude::*;
 
-/// This example shows various ways to configure texture materials in 3D
 fn main() {
     App::new()
         .add_plugins(DefaultPlugins)
diff --git a/examples/3d/update_gltf_scene.rs b/examples/3d/update_gltf_scene.rs
index 3a23e82028ab1..24eae1e50d3df 100644
--- a/examples/3d/update_gltf_scene.rs
+++ b/examples/3d/update_gltf_scene.rs
@@ -1,3 +1,6 @@
+//! Update a scene from a gltf file, either by spawning the scene as a child of another entity,
+//! or by accessing the entities of the scene
+
 use bevy::{prelude::*, scene::InstanceId};
 
 fn main() {
diff --git a/examples/3d/wireframe.rs b/examples/3d/wireframe.rs
index 96be8a9cbe881..957eeaee853a7 100644
--- a/examples/3d/wireframe.rs
+++ b/examples/3d/wireframe.rs
@@ -1,3 +1,5 @@
+//! Showcases wireframe rendering
+
 use bevy::{
     pbr::wireframe::{Wireframe, WireframeConfig, WireframePlugin},
     prelude::*,
diff --git a/examples/animation/animated_fox.rs b/examples/animation/animated_fox.rs
index 772208dd267e1..3432e859aaabb 100644
--- a/examples/animation/animated_fox.rs
+++ b/examples/animation/animated_fox.rs
@@ -1,3 +1,5 @@
+//! Plays animations from a skinned glTF.
+
 use bevy::prelude::*;
 
 fn main() {
diff --git a/examples/animation/custom_skinned_mesh.rs b/examples/animation/custom_skinned_mesh.rs
index 5216cd08a65de..404368db7dce7 100644
--- a/examples/animation/custom_skinned_mesh.rs
+++ b/examples/animation/custom_skinned_mesh.rs
@@ -1,3 +1,6 @@
+//! Skinned mesh example with mesh and joints data defined in code.
+//! Example taken from <https://github.com/KhronosGroup/glTF-Tutorials/blob/master/gltfTutorial/gltfTutorial_019_SimpleSkin.md>
+
 use std::f32::consts::PI;
 
 use bevy::{
@@ -10,8 +13,6 @@ use bevy::{
 };
 use rand::Rng;
 
-/// Skinned mesh example with mesh and joints data defined in code.
-/// Example taken from <https://github.com/KhronosGroup/glTF-Tutorials/blob/master/gltfTutorial/gltfTutorial_019_SimpleSkin.md>
 fn main() {
     App::new()
         .add_plugins(DefaultPlugins)
diff --git a/examples/animation/gltf_skinned_mesh.rs b/examples/animation/gltf_skinned_mesh.rs
index ba318e2256131..7cb8f90d113c3 100644
--- a/examples/animation/gltf_skinned_mesh.rs
+++ b/examples/animation/gltf_skinned_mesh.rs
@@ -1,9 +1,10 @@
+//! Skinned mesh example with mesh and joints data loaded from a glTF file.
+//! Example taken from <https://github.com/KhronosGroup/glTF-Tutorials/blob/master/gltfTutorial/gltfTutorial_019_SimpleSkin.md>
+
 use std::f32::consts::PI;
 
 use bevy::{pbr::AmbientLight, prelude::*, render::mesh::skinning::SkinnedMesh};
 
-/// Skinned mesh example with mesh and joints data loaded from a glTF file.
-/// Example taken from <https://github.com/KhronosGroup/glTF-Tutorials/blob/master/gltfTutorial/gltfTutorial_019_SimpleSkin.md>
 fn main() {
     App::new()
         .add_plugins(DefaultPlugins)
@@ -27,7 +28,7 @@ fn setup(mut commands: Commands, asset_server: Res<AssetServer>) {
     commands.spawn_scene(asset_server.load::<Scene, _>("models/SimpleSkin/SimpleSkin.gltf#Scene0"));
 }
 
-/// The scene hierachy currently looks somewhat like this:
+/// The scene hierarchy currently looks somewhat like this:
 ///
 /// ```ignore
 /// <Parent entity>
diff --git a/examples/app/custom_loop.rs b/examples/app/custom_loop.rs
index d845617f0c1f2..f9f1e607e2592 100644
--- a/examples/app/custom_loop.rs
+++ b/examples/app/custom_loop.rs
@@ -1,10 +1,11 @@
+//! This example demonstrates you can create a custom runner (to update an app manually). It reads
+//! lines from stdin and prints them from within the ecs.
+
 use bevy::prelude::*;
 use std::{io, io::BufRead};
 
 struct Input(String);
 
-/// This example demonstrates you can create a custom runner (to update an app manually). It reads
-/// lines from stdin and prints them from within the ecs.
 fn my_runner(mut app: App) {
     println!("Type stuff into the console");
     for line in io::stdin().lock().lines() {
diff --git a/examples/app/drag_and_drop.rs b/examples/app/drag_and_drop.rs
index 3615aab7eb89d..6dc64d50d3678 100644
--- a/examples/app/drag_and_drop.rs
+++ b/examples/app/drag_and_drop.rs
@@ -1,3 +1,5 @@
+//! An example that shows how to handle drag and drop of files in an app.
+
 use bevy::prelude::*;
 
 fn main() {
diff --git a/examples/app/empty.rs b/examples/app/empty.rs
index 032a096968636..758ff94555c16 100644
--- a/examples/app/empty.rs
+++ b/examples/app/empty.rs
@@ -1,3 +1,5 @@
+//! An empty application (does nothing)
+
 use bevy::prelude::*;
 
 fn main() {
diff --git a/examples/app/empty_defaults.rs b/examples/app/empty_defaults.rs
index 5aaacce1fcd4e..35950bbd6d705 100644
--- a/examples/app/empty_defaults.rs
+++ b/examples/app/empty_defaults.rs
@@ -1,3 +1,5 @@
+//! An empty application with default plugins
+
 use bevy::prelude::*;
 
 fn main() {
diff --git a/examples/app/headless.rs b/examples/app/headless.rs
index 4dbbcda903e2a..921bc1c16d84b 100644
--- a/examples/app/headless.rs
+++ b/examples/app/headless.rs
@@ -1,12 +1,12 @@
-use bevy::{app::ScheduleRunnerSettings, prelude::*, utils::Duration};
+//! This example only enables a minimal set of plugins required for bevy to run.
+//! You can also completely remove rendering / windowing Plugin code from bevy
+//! by making your import look like this in your Cargo.toml
+//!
+//! [dependencies]
+//! bevy = { version = "*", default-features = false }
+//! # replace "*" with the most recent version of bevy
 
-// This example only enables a minimal set of plugins required for bevy to run.
-// You can also completely remove rendering / windowing Plugin code from bevy
-// by making your import look like this in your Cargo.toml
-//
-// [dependencies]
-// bevy = { version = "*", default-features = false }
-// # replace "*" with the most recent version of bevy
+use bevy::{app::ScheduleRunnerSettings, prelude::*, utils::Duration};
 
 fn main() {
     // this app runs once
diff --git a/examples/app/headless_defaults.rs b/examples/app/headless_defaults.rs
index c29912567795e..e640b01ffba36 100644
--- a/examples/app/headless_defaults.rs
+++ b/examples/app/headless_defaults.rs
@@ -1,3 +1,5 @@
+//! An application that runs with default plugins, but without an actual renderer
+
 use bevy::{prelude::*, render::settings::WgpuSettings};
 
 fn main() {
diff --git a/examples/app/logs.rs b/examples/app/logs.rs
index cdc6b5db01274..ff4dfc151cd64 100644
--- a/examples/app/logs.rs
+++ b/examples/app/logs.rs
@@ -1,6 +1,6 @@
+//! This example illustrates how to use logs in bevy
 use bevy::prelude::*;
 
-/// This example illustrates how to use logs in bevy
 fn main() {
     App::new()
         // Uncomment this to override the default log settings:
diff --git a/examples/app/plugin.rs b/examples/app/plugin.rs
index 93600d943ffec..e757a62f645c7 100644
--- a/examples/app/plugin.rs
+++ b/examples/app/plugin.rs
@@ -1,8 +1,11 @@
+//! Demonstrates the creation and registration of a custom plugin
+//!
+//! Plugins are the foundation of Bevy. They are scoped sets of components, resources, and systems
+//! that provide a specific piece of functionality (generally the smaller the scope, the better).
+//! This example illustrates how to create a simple plugin that prints out a message.
+
 use bevy::{prelude::*, utils::Duration};
 
-/// Plugins are the foundation of Bevy. They are scoped sets of components, resources, and systems
-/// that provide a specific piece of functionality (generally the smaller the scope, the better).
-/// This example illustrates how to create a simple plugin that prints out a message.
 fn main() {
     App::new()
         .add_plugins(DefaultPlugins)
diff --git a/examples/app/plugin_group.rs b/examples/app/plugin_group.rs
index 0300f8a01f000..d898c20f350db 100644
--- a/examples/app/plugin_group.rs
+++ b/examples/app/plugin_group.rs
@@ -1,6 +1,8 @@
+//! Demonstrates the creation and registration of a custom plugin group
+//! [`PluginGroups`] are a way to group sets of plugins that should be registered together.
+
 use bevy::{app::PluginGroupBuilder, prelude::*};
 
-/// [`PluginGroups`] are a way to group sets of plugins that should be registered together.
 fn main() {
     App::new()
         // Two PluginGroups that are included with bevy are DefaultPlugins and MinimalPlugins
diff --git a/examples/app/return_after_run.rs b/examples/app/return_after_run.rs
index 7d4968c83e10b..fa88a3af668a3 100644
--- a/examples/app/return_after_run.rs
+++ b/examples/app/return_after_run.rs
@@ -1,3 +1,5 @@
+//! Show how to return to main after the Bevy app has exited
+
 use bevy::{prelude::*, winit::WinitSettings};
 
 fn main() {
diff --git a/examples/app/thread_pool_resources.rs b/examples/app/thread_pool_resources.rs
index b53273b584ac3..e49ab1636c621 100644
--- a/examples/app/thread_pool_resources.rs
+++ b/examples/app/thread_pool_resources.rs
@@ -1,7 +1,8 @@
+//! This example illustrates how to customize the thread pool used internally (e.g. to only use a
+//! certain number of threads).
+
 use bevy::prelude::*;
 
-/// This example illustrates how to customize the thread pool used internally (e.g. to only use a
-/// certain number of threads).
 fn main() {
     App::new()
         .insert_resource(DefaultTaskPoolOptions::with_num_threads(4))
diff --git a/examples/app/without_winit.rs b/examples/app/without_winit.rs
index 50aaa3880af20..637b9713f2d7b 100644
--- a/examples/app/without_winit.rs
+++ b/examples/app/without_winit.rs
@@ -1,3 +1,5 @@
+//! Create an application without winit (runs single time, no event loop)
+
 use bevy::prelude::*;
 use bevy::winit::WinitPlugin;
 
diff --git a/examples/asset/asset_loading.rs b/examples/asset/asset_loading.rs
index 4ca42e35035c7..39a08e7063b8f 100644
--- a/examples/asset/asset_loading.rs
+++ b/examples/asset/asset_loading.rs
@@ -1,6 +1,7 @@
+//! This example illustrates various ways to load assets
+
 use bevy::prelude::*;
 
-/// This example illustrates various ways to load assets
 fn main() {
     App::new()
         .insert_resource(Msaa { samples: 4 })
diff --git a/examples/asset/custom_asset.rs b/examples/asset/custom_asset.rs
index 820d62394eeb0..9df98e9d9aa2a 100644
--- a/examples/asset/custom_asset.rs
+++ b/examples/asset/custom_asset.rs
@@ -1,3 +1,5 @@
+//! Implements a custom asset loader
+
 use bevy::{
     asset::{AssetLoader, LoadContext, LoadedAsset},
     prelude::*,
diff --git a/examples/asset/custom_asset_io.rs b/examples/asset/custom_asset_io.rs
index af74a93d2ba3e..dcf62c5ab55d6 100644
--- a/examples/asset/custom_asset_io.rs
+++ b/examples/asset/custom_asset_io.rs
@@ -1,3 +1,7 @@
+//! Implements a custom asset io loader
+//! An [`AssetIo`] load is what the assert server uses to read the raw bytes of assets.
+//! It does not know anything about the asset formats, only how to talk the underlying storage.
+
 use bevy::{
     asset::{AssetIo, AssetIoError, Metadata},
     prelude::*,
@@ -21,7 +25,7 @@ impl AssetIo for CustomAssetIo {
     fn read_directory(
         &self,
         path: &Path,
-    ) -> Result<Box<dyn Iterator<Item = PathBuf>>, AssetIoError> {
+    ) -> Result<Box<dyn Iterator<Item=PathBuf>>, AssetIoError> {
         info!("read_directory({:?})", path);
         self.0.read_directory(path)
     }
diff --git a/examples/asset/hot_asset_reloading.rs b/examples/asset/hot_asset_reloading.rs
index 008133059068b..d219dbb110abc 100644
--- a/examples/asset/hot_asset_reloading.rs
+++ b/examples/asset/hot_asset_reloading.rs
@@ -1,8 +1,9 @@
+//! Hot reloading allows you to modify assets on disk and they will be "live reloaded" while your
+//! game is running. This lets you immediately see the results of your changes without restarting
+//! the game. This example illustrates hot reloading mesh changes.
+
 use bevy::{asset::AssetServerSettings, prelude::*};
 
-/// Hot reloading allows you to modify assets on disk and they will be "live reloaded" while your
-/// game is running. This lets you immediately see the results of your changes without restarting
-/// the game. This example illustrates hot reloading mesh changes.
 fn main() {
     App::new()
         // Tell the asset server to watch for asset changes on disk:
diff --git a/examples/async_tasks/async_compute.rs b/examples/async_tasks/async_compute.rs
index 9182ac48797fd..6a4039e5a3b22 100644
--- a/examples/async_tasks/async_compute.rs
+++ b/examples/async_tasks/async_compute.rs
@@ -1,3 +1,6 @@
+//! This example shows how to use the ECS and the [`AsyncComputeTaskPool`]
+//! to spawn, poll, and complete tasks across systems and system ticks.
+
 use bevy::{
     prelude::*,
     tasks::{AsyncComputeTaskPool, Task},
@@ -6,8 +9,6 @@ use futures_lite::future;
 use rand::Rng;
 use std::time::{Duration, Instant};
 
-/// This example shows how to use the ECS and the [`AsyncComputeTaskPool`]
-/// to spawn, poll, and complete tasks across systems and system ticks.
 fn main() {
     App::new()
         .insert_resource(Msaa { samples: 4 })
diff --git a/examples/async_tasks/external_source_external_thread.rs b/examples/async_tasks/external_source_external_thread.rs
index 6b2cec163c2b1..7be6624735f84 100644
--- a/examples/async_tasks/external_source_external_thread.rs
+++ b/examples/async_tasks/external_source_external_thread.rs
@@ -1,3 +1,5 @@
+//! How to use an external thread to run an infinite task and communicate with a channel
+
 use bevy::prelude::*;
 // Using crossbeam_channel instead of std as std `Receiver` is `!Sync`
 use crossbeam_channel::{bounded, Receiver};
diff --git a/examples/audio/audio.rs b/examples/audio/audio.rs
index 2ff6f92ba185a..d318c0bf4725f 100644
--- a/examples/audio/audio.rs
+++ b/examples/audio/audio.rs
@@ -1,6 +1,7 @@
+//! This example illustrates how to load and play an audio file
+
 use bevy::prelude::*;
 
-/// This example illustrates how to load and play an audio file
 fn main() {
     App::new()
         .add_plugins(DefaultPlugins)
diff --git a/examples/audio/audio_control.rs b/examples/audio/audio_control.rs
index ea218b92489d0..8db093c3f9bfc 100644
--- a/examples/audio/audio_control.rs
+++ b/examples/audio/audio_control.rs
@@ -1,6 +1,7 @@
+//! This example illustrates how to load and play an audio file, and control how it's played
+
 use bevy::{audio::AudioSink, prelude::*};
 
-/// This example illustrates how to load and play an audio file, and control how it's played
 fn main() {
     App::new()
         .add_plugins(DefaultPlugins)
diff --git a/examples/diagnostics/custom_diagnostic.rs b/examples/diagnostics/custom_diagnostic.rs
index 7f289d9f5b71e..62d85b147fac0 100644
--- a/examples/diagnostics/custom_diagnostic.rs
+++ b/examples/diagnostics/custom_diagnostic.rs
@@ -1,9 +1,10 @@
+//! This example illustrates how to create a custom diagnostic
+
 use bevy::{
     diagnostic::{Diagnostic, DiagnosticId, Diagnostics, LogDiagnosticsPlugin},
     prelude::*,
 };
 
-/// This example illustrates how to create a custom diagnostic
 fn main() {
     App::new()
         .add_plugins(DefaultPlugins)
diff --git a/examples/diagnostics/log_diagnostics.rs b/examples/diagnostics/log_diagnostics.rs
index 8c1447e60b0ab..47ed62e99ae6a 100644
--- a/examples/diagnostics/log_diagnostics.rs
+++ b/examples/diagnostics/log_diagnostics.rs
@@ -1,3 +1,5 @@
+//! Add a plugin that logs diagnostics, like frames per second (FPS), to the console
+
 use bevy::{
     diagnostic::{FrameTimeDiagnosticsPlugin, LogDiagnosticsPlugin},
     prelude::*,
diff --git a/examples/ecs/component_change_detection.rs b/examples/ecs/component_change_detection.rs
index 01473c7749bc0..87b947ca220c0 100644
--- a/examples/ecs/component_change_detection.rs
+++ b/examples/ecs/component_change_detection.rs
@@ -1,7 +1,8 @@
+//! This example illustrates how to react to component change
+
 use bevy::prelude::*;
 use rand::Rng;
 
-// This example illustrates how to react to component change
 fn main() {
     App::new()
         .add_plugins(DefaultPlugins)
diff --git a/examples/ecs/custom_query_param.rs b/examples/ecs/custom_query_param.rs
index b18275794d429..7804ad84ddff9 100644
--- a/examples/ecs/custom_query_param.rs
+++ b/examples/ecs/custom_query_param.rs
@@ -1,22 +1,23 @@
+//! This examples illustrates the usage of the `WorldQuery` derive macro, which allows
+//! defining custom query and filter types.
+//!
+//! While regular tuple queries work great in most of simple scenarios, using custom queries
+//! declared as named structs can bring the following advantages:
+//! - They help to avoid destructuring or using `q.0, q.1, ...` access pattern.
+//! - Adding, removing components or changing items order with structs greatly reduces maintenance
+//!   burden, as you don't need to update statements that destructure tuples, care about order
+//!   of elements, etc. Instead, you can just add or remove places where a certain element is used.
+//! - Named structs enable the composition pattern, that makes query types easier to re-use.
+//! - You can bypass the limit of 15 components that exists for query tuples.
+//!
+//! For more details on the `WorldQuery` derive macro, see the trait documentation.
+
 use bevy::{
     ecs::{component::Component, query::WorldQuery},
     prelude::*,
 };
 use std::fmt::Debug;
 
-/// This examples illustrates the usage of the `WorldQuery` derive macro, which allows
-/// defining custom query and filter types.
-///
-/// While regular tuple queries work great in most of simple scenarios, using custom queries
-/// declared as named structs can bring the following advantages:
-/// - They help to avoid destructuring or using `q.0, q.1, ...` access pattern.
-/// - Adding, removing components or changing items order with structs greatly reduces maintenance
-///   burden, as you don't need to update statements that destructure tuples, care about order
-///   of elements, etc. Instead, you can just add or remove places where a certain element is used.
-/// - Named structs enable the composition pattern, that makes query types easier to re-use.
-/// - You can bypass the limit of 15 components that exists for query tuples.
-///
-/// For more details on the `WorldQuery` derive macro, see the trait documentation.
 fn main() {
     App::new()
         .add_startup_system(spawn)
diff --git a/examples/ecs/ecs_guide.rs b/examples/ecs/ecs_guide.rs
index c199a0019d5da..b27ed06f57094 100644
--- a/examples/ecs/ecs_guide.rs
+++ b/examples/ecs/ecs_guide.rs
@@ -1,3 +1,29 @@
+//! This is a guided introduction to Bevy's "Entity Component System" (ECS)
+//! All Bevy app logic is built using the ECS pattern, so definitely pay attention!
+//!
+//! Why ECS?
+//! * Data oriented: Functionality is driven by data
+//! * Clean Architecture: Loose coupling of functionality / prevents deeply nested inheritance
+//! * High Performance: Massively parallel and cache friendly
+//!
+//! ECS Definitions:
+//!
+//! Component: just a normal Rust data type. generally scoped to a single piece of functionality
+//!     Examples: position, velocity, health, color, name
+//!
+//! Entity: a collection of components with a unique id
+//!     Examples: Entity1 { Name("Alice"), Position(0, 0) },
+//!               Entity2 { Name("Bill"), Position(10, 5) }
+//!
+//! Resource: a shared global piece of data
+//!     Examples: asset storage, events, system state
+//!
+//! System: runs logic on entities, components, and resources
+//!     Examples: move system, damage system
+//!
+//! Now that you know a little bit about ECS, lets look at some Bevy code!
+//! We will now make a simple "game" to illustrate what Bevy's ECS looks like in practice.
+
 use bevy::{
     app::{AppExit, ScheduleRunnerPlugin, ScheduleRunnerSettings},
     ecs::schedule::ReportExecutionOrderAmbiguities,
@@ -7,32 +33,6 @@ use bevy::{
 };
 use rand::random;
 
-/// This is a guided introduction to Bevy's "Entity Component System" (ECS)
-/// All Bevy app logic is built using the ECS pattern, so definitely pay attention!
-///
-/// Why ECS?
-/// * Data oriented: Functionality is driven by data
-/// * Clean Architecture: Loose coupling of functionality / prevents deeply nested inheritance
-/// * High Performance: Massively parallel and cache friendly
-///
-/// ECS Definitions:
-///
-/// Component: just a normal Rust data type. generally scoped to a single piece of functionality
-///     Examples: position, velocity, health, color, name
-///
-/// Entity: a collection of components with a unique id
-///     Examples: Entity1 { Name("Alice"), Position(0, 0) }, Entity2 { Name("Bill"), Position(10, 5)
-/// }
-
-/// Resource: a shared global piece of data
-///     Examples: asset storage, events, system state
-///
-/// System: runs logic on entities, components, and resources
-///     Examples: move system, damage system
-///
-/// Now that you know a little bit about ECS, lets look at some Bevy code!
-/// We will now make a simple "game" to illustrate what Bevy's ECS looks like in practice.
-
 // COMPONENTS: Pieces of functionality we add to entities. These are just normal Rust data types
 //
 
diff --git a/examples/ecs/event.rs b/examples/ecs/event.rs
index bb04b14004529..f4c93c44d47a0 100644
--- a/examples/ecs/event.rs
+++ b/examples/ecs/event.rs
@@ -1,7 +1,8 @@
+//! This example creates a new event, a system that triggers the event once per second,
+//! and a system that prints a message whenever the event is received.
+
 use bevy::prelude::*;
 
-/// This example creates a new event, a system that triggers the event once per second,
-/// and a system that prints a message whenever the event is received.
 fn main() {
     App::new()
         .add_plugins(DefaultPlugins)
diff --git a/examples/ecs/fixed_timestep.rs b/examples/ecs/fixed_timestep.rs
index f89d3046689ee..999563c258e0d 100644
--- a/examples/ecs/fixed_timestep.rs
+++ b/examples/ecs/fixed_timestep.rs
@@ -1,3 +1,5 @@
+//! Shows how to create systems that run every fixed timestep, rather than every tick
+
 use bevy::{
     core::{FixedTimestep, FixedTimesteps},
     prelude::*,
diff --git a/examples/ecs/generic_system.rs b/examples/ecs/generic_system.rs
index 2e3a13099989f..0d3f3c31776d8 100644
--- a/examples/ecs/generic_system.rs
+++ b/examples/ecs/generic_system.rs
@@ -1,15 +1,15 @@
-use bevy::{ecs::component::Component, prelude::*};
+//! Generic types allow us to reuse logic across many related systems,
+//! allowing us to specialize our function's behavior based on which type (or types) are passed in.
+//!
+//! This is commonly useful for working on related components or resources,
+//! where we want to have unique types for querying purposes but want them all to work the same way.
+//! This is particularly powerful when combined with user-defined traits to add more functionality to these related types.
+//! Remember to insert a specialized copy of the system into the schedule for each type that you want to operate on!
+//!
+//! For more advice on working with generic types in Rust, check out <https://doc.rust-lang.org/book/ch10-01-syntax.html>
+//! or <https://doc.rust-lang.org/rust-by-example/generics.html>
 
-/// Generic types allow us to reuse logic across many related systems,
-/// allowing us to specialize our function's behavior based on which type (or types) are passed in.
-///
-/// This is commonly useful for working on related components or resources,
-/// where we want to have unique types for querying purposes but want them all to work the same way.
-/// This is particularly powerful when combined with user-defined traits to add more functionality to these related types.
-/// Remember to insert a specialized copy of the system into the schedule for each type that you want to operate on!
-///
-/// For more advice on working with generic types in Rust, check out <https://doc.rust-lang.org/book/ch10-01-syntax.html>
-/// or <https://doc.rust-lang.org/rust-by-example/generics.html>
+use bevy::{ecs::component::Component, prelude::*};
 
 #[derive(Debug, Clone, Eq, PartialEq, Hash)]
 enum AppState {
diff --git a/examples/ecs/hierarchy.rs b/examples/ecs/hierarchy.rs
index c67dfac85e4a5..4dde980b62827 100644
--- a/examples/ecs/hierarchy.rs
+++ b/examples/ecs/hierarchy.rs
@@ -1,3 +1,5 @@
+//! Creates a hierarchy of parents and children entities
+
 use bevy::prelude::*;
 
 fn main() {
diff --git a/examples/ecs/iter_combinations.rs b/examples/ecs/iter_combinations.rs
index e4122f17f7cae..73ab1584086c0 100644
--- a/examples/ecs/iter_combinations.rs
+++ b/examples/ecs/iter_combinations.rs
@@ -1,3 +1,5 @@
+//! Shows how to iterate over combinations of query results.
+
 use bevy::{core::FixedTimestep, pbr::AmbientLight, prelude::*, render::camera::Camera};
 use rand::{thread_rng, Rng};
 
diff --git a/examples/ecs/parallel_query.rs b/examples/ecs/parallel_query.rs
index a70eecf6d8b1a..646cf0203baad 100644
--- a/examples/ecs/parallel_query.rs
+++ b/examples/ecs/parallel_query.rs
@@ -1,3 +1,5 @@
+//! Illustrates parallel queries with `ParallelIterator`
+
 use bevy::{prelude::*, tasks::prelude::*};
 use rand::random;
 
diff --git a/examples/ecs/removal_detection.rs b/examples/ecs/removal_detection.rs
index 876ff4f9164f4..c8bd75e063da9 100644
--- a/examples/ecs/removal_detection.rs
+++ b/examples/ecs/removal_detection.rs
@@ -1,4 +1,4 @@
-// This example shows how you can know when a `Component` has been removed, so you can react to it.
+//! This example shows how you can know when a `Component` has been removed, so you can react to it.
 
 use bevy::prelude::*;
 
diff --git a/examples/ecs/startup_system.rs b/examples/ecs/startup_system.rs
index 82437b03af99e..a56b1aa39bc24 100644
--- a/examples/ecs/startup_system.rs
+++ b/examples/ecs/startup_system.rs
@@ -1,3 +1,5 @@
+//! Demonstrates a startup system (one that runs once when the app starts up)
+
 use bevy::prelude::*;
 
 fn main() {
diff --git a/examples/ecs/state.rs b/examples/ecs/state.rs
index 2371783ea1e7d..82a07f2f22836 100644
--- a/examples/ecs/state.rs
+++ b/examples/ecs/state.rs
@@ -1,7 +1,8 @@
+//! This example illustrates how to use [`States`] to control transitioning from a `Menu` state to
+//! an `InGame` state.
+
 use bevy::prelude::*;
 
-/// This example illustrates how to use [`States`] to control transitioning from a `Menu` state to
-/// an `InGame` state.
 fn main() {
     App::new()
         .add_plugins(DefaultPlugins)
diff --git a/examples/ecs/system_chaining.rs b/examples/ecs/system_chaining.rs
index 026fc0f220cef..6bab5a46c38f5 100644
--- a/examples/ecs/system_chaining.rs
+++ b/examples/ecs/system_chaining.rs
@@ -1,3 +1,5 @@
+//! Illustrates how to use States to control transitioning from a Menu state to an InGame state
+
 use anyhow::Result;
 use bevy::prelude::*;
 
diff --git a/examples/ecs/system_param.rs b/examples/ecs/system_param.rs
index fdb9e5038d885..ddebd5fb17246 100644
--- a/examples/ecs/system_param.rs
+++ b/examples/ecs/system_param.rs
@@ -1,6 +1,7 @@
+//! This example creates a [`SystemParam`] struct that counts the number of players
+
 use bevy::{ecs::system::SystemParam, prelude::*};
 
-/// This example creates a [`SystemParam`] struct that counts the number of players
 fn main() {
     App::new()
         .insert_resource(PlayerCount(0))
diff --git a/examples/ecs/system_sets.rs b/examples/ecs/system_sets.rs
index 642f9f49d2810..fe9e4c9b62313 100644
--- a/examples/ecs/system_sets.rs
+++ b/examples/ecs/system_sets.rs
@@ -1,3 +1,26 @@
+//! This example realizes the following scheme:
+//!
+//! ```none
+//! Physics                     (Criteria: App has run < 1.0 seconds)
+//!     \--> update_velocity        (via label PhysicsSystem::UpdateVelocity)
+//!     \--> movement               (via label PhysicsSystem::Movement)
+//! PostPhysics                 (Criteria: Resource `done` is false)
+//!     \--> collision || sfx
+//! Exit                        (Criteria: Resource `done` is true)
+//!     \--> exit
+//! ```
+//!
+//! The `Physics` label represents a [`SystemSet`] containing two systems.
+//! This set's criteria is to stop after a second has elapsed.
+//! The two systems (`update_velocity`, `movement`) run in a specified order.
+//!
+//! Another label `PostPhysics` uses run criteria to only run after `Physics` has finished.
+//! This set's criteria is to run only when _not done_, as specified via a resource.
+//! The two systems here (collision, sfx) are not specified to run in any order, and the actual
+//! ordering can then change between invocations.
+//!
+//! Lastly a system with run criterion _done_ is used to exit the app.
+
 use bevy::{app::AppExit, ecs::schedule::ShouldRun, prelude::*};
 
 /// A [`SystemLabel`] can be applied as a label to systems and system sets,
@@ -16,28 +39,6 @@ struct PostPhysics;
 #[derive(Default)]
 struct Done(bool);
 
-/// This example realizes the following scheme:
-///
-/// ```none
-/// Physics                     (Criteria: App has run < 1.0 seconds)
-///     \--> update_velocity        (via label PhysicsSystem::UpdateVelocity)
-///     \--> movement               (via label PhysicsSystem::Movement)
-/// PostPhysics                 (Criteria: Resource `done` is false)
-///     \--> collision || sfx
-/// Exit                        (Criteria: Resource `done` is true)
-///     \--> exit
-/// ```
-///
-/// The `Physics` label represents a [`SystemSet`] containing two systems.
-/// This set's criteria is to stop after a second has elapsed.
-/// The two systems (`update_velocity`, `movement`) run in a specified order.
-///
-/// Another label `PostPhysics` uses run criteria to only run after `Physics` has finished.
-/// This set's criteria is to run only when _not done_, as specified via a resource.
-/// The two systems here (collision, sfx) are not specified to run in any order, and the actual
-/// ordering can then change between invocations.
-///
-/// Lastly a system with run criterion _done_ is used to exit the app.
 fn main() {
     App::new()
         .add_plugins(DefaultPlugins)
diff --git a/examples/ecs/timers.rs b/examples/ecs/timers.rs
index 4ed3767555039..433901259e61e 100644
--- a/examples/ecs/timers.rs
+++ b/examples/ecs/timers.rs
@@ -1,3 +1,5 @@
+//! Illustrates ticking `Timer` resources inside systems and handling their state
+
 use bevy::{log::info, prelude::*};
 
 fn main() {
diff --git a/examples/games/alien_cake_addict.rs b/examples/games/alien_cake_addict.rs
index 4e3c626575616..07ef9bc64ee56 100644
--- a/examples/games/alien_cake_addict.rs
+++ b/examples/games/alien_cake_addict.rs
@@ -1,3 +1,5 @@
+//! Eat the cakes. Eat them all. An example 3D game
+
 use bevy::{core::FixedTimestep, ecs::schedule::SystemSet, prelude::*, render::camera::Camera3d};
 use rand::Rng;
 
@@ -84,7 +86,7 @@ fn setup_cameras(mut commands: Commands, mut game: ResMut<Game>) {
             2.0 * BOARD_SIZE_J as f32 / 3.0,
             BOARD_SIZE_J as f32 / 2.0 - 0.5,
         )
-        .looking_at(game.camera_is_focus, Vec3::Y),
+            .looking_at(game.camera_is_focus, Vec3::Y),
         ..default()
     });
     commands.spawn_bundle(UiCameraBundle::default());
@@ -268,12 +270,12 @@ fn focus_camera(
                 .translation
                 .lerp(bonus_transform.translation, 0.5);
         }
-    // otherwise, if there is only a player, target the player
+        // otherwise, if there is only a player, target the player
     } else if let Some(player_entity) = game.player.entity {
         if let Ok(player_transform) = transforms.p1().get(player_entity) {
             game.camera_should_focus = player_transform.translation;
         }
-    // otherwise, target the middle
+        // otherwise, target the middle
     } else {
         game.camera_should_focus = Vec3::from(RESET_FOCUS);
     }
diff --git a/examples/games/game_menu.rs b/examples/games/game_menu.rs
index 78167cb33a7d0..90fb5fcf4c185 100644
--- a/examples/games/game_menu.rs
+++ b/examples/games/game_menu.rs
@@ -1,8 +1,8 @@
-use bevy::prelude::*;
+//! This example will display a simple menu using Bevy UI where you can start a new game,
+//! change some settings or quit. There is no actual game, it will just display the current
+//! settings for 5 seconds before going back to the menu.
 
-// This example will display a simple menu using Bevy UI where you can start a new game,
-// change some settings or quit. There is no actual game, it will just display the current
-// settings for 5 seconds before going back to the menu.
+use bevy::prelude::*;
 
 const TEXT_COLOR: Color = Color::rgb(0.9, 0.9, 0.9);
 
diff --git a/examples/input/char_input_events.rs b/examples/input/char_input_events.rs
index 5e478a35cc32f..1fbb7af53b7d4 100644
--- a/examples/input/char_input_events.rs
+++ b/examples/input/char_input_events.rs
@@ -1,3 +1,5 @@
+//! Prints out all chars as they are inputted.
+
 use bevy::{prelude::*, window::ReceivedCharacter};
 
 fn main() {
diff --git a/examples/input/gamepad_input.rs b/examples/input/gamepad_input.rs
index d69f2aa1aaaa4..c140a311f4655 100644
--- a/examples/input/gamepad_input.rs
+++ b/examples/input/gamepad_input.rs
@@ -1,3 +1,5 @@
+//! Shows handling of gamepad input, connections, and disconnections
+
 use bevy::{input::gamepad::GamepadButton, prelude::*};
 
 fn main() {
diff --git a/examples/input/gamepad_input_events.rs b/examples/input/gamepad_input_events.rs
index 570e60b66b779..69cf09229dbc5 100644
--- a/examples/input/gamepad_input_events.rs
+++ b/examples/input/gamepad_input_events.rs
@@ -1,3 +1,5 @@
+//! Iterates and prints gamepad input and connection events
+
 use bevy::{
     input::gamepad::{GamepadEvent, GamepadEventType},
     prelude::*,
diff --git a/examples/input/keyboard_input.rs b/examples/input/keyboard_input.rs
index 0d6becefd90d3..7df695f3cad9f 100644
--- a/examples/input/keyboard_input.rs
+++ b/examples/input/keyboard_input.rs
@@ -1,3 +1,5 @@
+//! Demonstrates handling a key press/release
+
 use bevy::{
     input::{keyboard::KeyCode, Input},
     prelude::*,
diff --git a/examples/input/keyboard_input_events.rs b/examples/input/keyboard_input_events.rs
index e9de57d5b3e5f..94e5e61519e1b 100644
--- a/examples/input/keyboard_input_events.rs
+++ b/examples/input/keyboard_input_events.rs
@@ -1,3 +1,5 @@
+//! Prints out all keyboard events
+
 use bevy::{input::keyboard::KeyboardInput, prelude::*};
 
 fn main() {
diff --git a/examples/input/keyboard_modifiers.rs b/examples/input/keyboard_modifiers.rs
index 5b6ebfa3afce2..1691ea94754ec 100644
--- a/examples/input/keyboard_modifiers.rs
+++ b/examples/input/keyboard_modifiers.rs
@@ -1,3 +1,5 @@
+//! Demonstrates using key modifiers (ctrl, shift)
+
 use bevy::{
     input::{keyboard::KeyCode, Input},
     prelude::*,
diff --git a/examples/input/mouse_grab.rs b/examples/input/mouse_grab.rs
index 7b125d205db48..a3654d9da80e7 100644
--- a/examples/input/mouse_grab.rs
+++ b/examples/input/mouse_grab.rs
@@ -1,3 +1,5 @@
+//! Demonstrates handling a mouse button press/release
+
 use bevy::prelude::*;
 
 fn main() {
diff --git a/examples/input/mouse_input.rs b/examples/input/mouse_input.rs
index 6c214b0cf2675..a0ec783d84a5d 100644
--- a/examples/input/mouse_input.rs
+++ b/examples/input/mouse_input.rs
@@ -1,3 +1,5 @@
+//! Prints out all mouse events (buttons, movement, etc.)
+
 use bevy::prelude::*;
 
 fn main() {
diff --git a/examples/input/mouse_input_events.rs b/examples/input/mouse_input_events.rs
index 16c2a7a74a1fa..0c12190b23aef 100644
--- a/examples/input/mouse_input_events.rs
+++ b/examples/input/mouse_input_events.rs
@@ -1,3 +1,5 @@
+//! Demonstrates how to grab the mouse, locking the cursor to the app's screen
+
 use bevy::{
     input::mouse::{MouseButtonInput, MouseMotion, MouseWheel},
     prelude::*,
diff --git a/examples/input/touch_input.rs b/examples/input/touch_input.rs
index 1616959fc1ec6..8a1e99bbd4ce3 100644
--- a/examples/input/touch_input.rs
+++ b/examples/input/touch_input.rs
@@ -1,3 +1,5 @@
+//! Displays touch presses, releases, and cancels
+
 use bevy::{input::touch::*, prelude::*};
 
 fn main() {
diff --git a/examples/input/touch_input_events.rs b/examples/input/touch_input_events.rs
index 49cecfcd1cf4f..7f940e6ee730d 100644
--- a/examples/input/touch_input_events.rs
+++ b/examples/input/touch_input_events.rs
@@ -1,3 +1,5 @@
+//! Prints out all touch inputs
+
 use bevy::{input::touch::*, prelude::*};
 
 fn main() {
diff --git a/examples/reflection/generic_reflection.rs b/examples/reflection/generic_reflection.rs
index 9fba61831cec1..f6261e0c82751 100644
--- a/examples/reflection/generic_reflection.rs
+++ b/examples/reflection/generic_reflection.rs
@@ -1,10 +1,12 @@
+//! Demonstrates how reflection in Bevy provides a way to dynamically interact with Rust types
+
 use bevy::{prelude::*, reflect::TypeRegistry};
 use std::any::TypeId;
 
-/// You must manually register each instance of a generic type
 fn main() {
     App::new()
         .add_plugins(DefaultPlugins)
+        // You must manually register each instance of a generic type
         .register_type::<MyType<u32>>()
         .add_startup_system(setup)
         .run();
diff --git a/examples/reflection/reflection.rs b/examples/reflection/reflection.rs
index 24f522614e07e..5c90f1d1f3969 100644
--- a/examples/reflection/reflection.rs
+++ b/examples/reflection/reflection.rs
@@ -1,3 +1,8 @@
+//! This example illustrates how "reflection" works in Bevy.
+//! Reflection provide a way to dynamically interact with Rust types, such as accessing fields
+//! by their string name. Reflection is a core part of Bevy and enables a number of interesting
+//! scenarios (like scenes).
+
 use bevy::{
     prelude::*,
     reflect::{
@@ -7,9 +12,6 @@ use bevy::{
 };
 use serde::de::DeserializeSeed;
 
-/// This example illustrates how "reflection" works in Bevy. Reflection provide a way to dynamically
-/// interact with Rust types, such as accessing fields by their string name. Reflection is a core
-/// part of Bevy and enables a number of interesting scenarios (like scenes).
 fn main() {
     App::new()
         .add_plugins(DefaultPlugins)
diff --git a/examples/reflection/reflection_types.rs b/examples/reflection/reflection_types.rs
index 8df74149c7c5c..255b671104ff0 100644
--- a/examples/reflection/reflection_types.rs
+++ b/examples/reflection/reflection_types.rs
@@ -1,3 +1,5 @@
+//! This example illustrates the various reflection types available
+
 use bevy::{
     prelude::*,
     reflect::{DynamicList, ReflectRef},
@@ -5,7 +7,6 @@ use bevy::{
 };
 use serde::{Deserialize, Serialize};
 
-/// This example illustrates the various reflection types available
 fn main() {
     App::new()
         .add_plugins(DefaultPlugins)
diff --git a/examples/reflection/trait_reflection.rs b/examples/reflection/trait_reflection.rs
index 9dba2f34ffc51..28cc81fc18467 100644
--- a/examples/reflection/trait_reflection.rs
+++ b/examples/reflection/trait_reflection.rs
@@ -1,3 +1,5 @@
+//! Allows reflection with trait objects
+
 use bevy::{prelude::*, reflect::TypeRegistry};
 
 fn main() {
diff --git a/examples/scene/scene.rs b/examples/scene/scene.rs
index e7b566dc1332b..0216be872b4c3 100644
--- a/examples/scene/scene.rs
+++ b/examples/scene/scene.rs
@@ -1,6 +1,7 @@
+//! This example illustrates loading and saving scenes from files
+
 use bevy::{prelude::*, reflect::TypeRegistry, utils::Duration};
 
-/// This example illustrates loading and saving scenes from files
 fn main() {
     App::new()
         .add_plugins(DefaultPlugins)
diff --git a/examples/shader/animate_shader.rs b/examples/shader/animate_shader.rs
index 2af1d34b85bf8..0bcc860bf1ebd 100644
--- a/examples/shader/animate_shader.rs
+++ b/examples/shader/animate_shader.rs
@@ -1,3 +1,6 @@
+//! Shows how to pass changing data like the time since startup into a shader, using a custom
+//! specialized pipeline.
+
 use bevy::{
     core_pipeline::Transparent3d,
     ecs::system::{lifetimeless::SRes, SystemParamItem},
@@ -85,7 +88,7 @@ fn extract_custom_material(
 ) {
     let mut values = Vec::with_capacity(*previous_len);
     for entity in query.iter_mut() {
-        values.push((entity, (CustomMaterial,)));
+        values.push((entity, (CustomMaterial, )));
     }
     *previous_len = values.len();
     commands.insert_or_spawn_batch(values);
@@ -244,6 +247,7 @@ type DrawCustom = (
 );
 
 struct SetTimeBindGroup<const I: usize>;
+
 impl<const I: usize> EntityRenderCommand for SetTimeBindGroup<I> {
     type Param = SRes<TimeMeta>;
 
diff --git a/examples/shader/compute_shader_game_of_life.rs b/examples/shader/compute_shader_game_of_life.rs
index 0725bbacc7ea2..d2ffb80c1ba98 100644
--- a/examples/shader/compute_shader_game_of_life.rs
+++ b/examples/shader/compute_shader_game_of_life.rs
@@ -1,3 +1,5 @@
+//! A compute shader simulating Conway's Game of Life
+
 use bevy::{
     core_pipeline::node::MAIN_PASS_DEPENDENCIES,
     prelude::*,
@@ -77,6 +79,7 @@ impl Plugin for GameOfLifeComputePlugin {
 
 #[derive(Deref)]
 struct GameOfLifeImage(Handle<Image>);
+
 struct GameOfLifeImageBindGroup(BindGroup);
 
 fn extract_game_of_life_image(mut commands: Commands, image: Res<GameOfLifeImage>) {
@@ -180,14 +183,14 @@ impl render_graph::Node for GameOfLifeNode {
         match self.state {
             GameOfLifeState::Loading => {
                 if let CachedPipelineState::Ok(_) =
-                    pipeline_cache.get_compute_pipeline_state(pipeline.init_pipeline)
+                pipeline_cache.get_compute_pipeline_state(pipeline.init_pipeline)
                 {
                     self.state = GameOfLifeState::Init
                 }
             }
             GameOfLifeState::Init => {
                 if let CachedPipelineState::Ok(_) =
-                    pipeline_cache.get_compute_pipeline_state(pipeline.update_pipeline)
+                pipeline_cache.get_compute_pipeline_state(pipeline.update_pipeline)
                 {
                     self.state = GameOfLifeState::Update
                 }
diff --git a/examples/shader/custom_vertex_attribute.rs b/examples/shader/custom_vertex_attribute.rs
index 44ef9d0a18553..9453245f8ea23 100644
--- a/examples/shader/custom_vertex_attribute.rs
+++ b/examples/shader/custom_vertex_attribute.rs
@@ -1,3 +1,5 @@
+//! Illustrates creating a custom shader material that reads a mesh's custom vertex attribute.
+
 use bevy::{
     ecs::system::{lifetimeless::SRes, SystemParamItem},
     pbr::MaterialPipeline,
diff --git a/examples/shader/shader_defs.rs b/examples/shader/shader_defs.rs
index 5be3ad6267822..d6e8246e16075 100644
--- a/examples/shader/shader_defs.rs
+++ b/examples/shader/shader_defs.rs
@@ -1,3 +1,6 @@
+//! Demonstrates creating a custom material that uses "shaders defs", a tool to selectively
+//! toggle parts of a shader
+
 use bevy::{
     core_pipeline::Transparent3d,
     pbr::{
diff --git a/examples/shader/shader_instancing.rs b/examples/shader/shader_instancing.rs
index 5698c3325b829..b3b04219e4e0f 100644
--- a/examples/shader/shader_instancing.rs
+++ b/examples/shader/shader_instancing.rs
@@ -1,3 +1,5 @@
+//! A custom shader showing off rendering a mesh multiple times in one draw call.
+
 use bevy::{
     core_pipeline::Transparent3d,
     ecs::system::{lifetimeless::*, SystemParamItem},
@@ -64,6 +66,7 @@ fn setup(mut commands: Commands, mut meshes: ResMut<Assets<Mesh>>) {
 
 #[derive(Component, Deref)]
 struct InstanceMaterialData(Vec<InstanceData>);
+
 impl ExtractComponent for InstanceMaterialData {
     type Query = &'static InstanceMaterialData;
     type Filter = ();
@@ -226,6 +229,7 @@ type DrawCustom = (
 );
 
 pub struct DrawMeshInstanced;
+
 impl EntityRenderCommand for DrawMeshInstanced {
     type Param = (
         SRes<RenderAssets<Mesh>>,
diff --git a/examples/shader/shader_material.rs b/examples/shader/shader_material.rs
index 97db298ddaf9a..e56a21b5bca4c 100644
--- a/examples/shader/shader_material.rs
+++ b/examples/shader/shader_material.rs
@@ -1,3 +1,5 @@
+//! A custom shader sampling a texture with view-independent UV coordinates
+
 use bevy::{
     ecs::system::{lifetimeless::SRes, SystemParamItem},
     pbr::MaterialPipeline,
diff --git a/examples/shader/shader_material_glsl.rs b/examples/shader/shader_material_glsl.rs
index 7e405157ce99f..c09ea8b2baefa 100644
--- a/examples/shader/shader_material_glsl.rs
+++ b/examples/shader/shader_material_glsl.rs
@@ -1,3 +1,5 @@
+//! A custom shader using the GLSL shading language.
+
 use bevy::{
     ecs::system::{lifetimeless::SRes, SystemParamItem},
     pbr::{MaterialPipeline, SpecializedMaterial},
diff --git a/examples/shader/shader_material_screenspace_texture.rs b/examples/shader/shader_material_screenspace_texture.rs
index 1adacc76067fa..a23317da127b5 100644
--- a/examples/shader/shader_material_screenspace_texture.rs
+++ b/examples/shader/shader_material_screenspace_texture.rs
@@ -1,3 +1,5 @@
+//! A custom shader sampling a texture with view-independent UV coordinates
+
 use bevy::{
     ecs::system::{lifetimeless::SRes, SystemParamItem},
     pbr::MaterialPipeline,
diff --git a/examples/stress_tests/bevymark.rs b/examples/stress_tests/bevymark.rs
index 358ec81462890..e651948d96a9d 100644
--- a/examples/stress_tests/bevymark.rs
+++ b/examples/stress_tests/bevymark.rs
@@ -1,3 +1,7 @@
+//! This example provides a 2D benchmark.
+//!
+//! Usage: spawn more entities by clicking on the screen.
+
 use bevy::{
     core::FixedTimestep,
     diagnostic::{Diagnostics, FrameTimeDiagnosticsPlugin, LogDiagnosticsPlugin},
@@ -22,9 +26,6 @@ struct Bird {
     velocity: Vec3,
 }
 
-/// This example provides a 2D benchmark.
-///
-/// Usage: spawn more entities by clicking on the screen.
 fn main() {
     App::new()
         .insert_resource(WindowDescriptor {
diff --git a/examples/stress_tests/many_cubes.rs b/examples/stress_tests/many_cubes.rs
index 82f9519e20a09..3405bf1d1c061 100644
--- a/examples/stress_tests/many_cubes.rs
+++ b/examples/stress_tests/many_cubes.rs
@@ -1,8 +1,21 @@
+//! Simple benchmark to test per-entity draw overhead
+//!
+//! To a realistic performance result, run this in release mode.
+//! `cargo run --example many_cubes --release`
+//!
+//! Per default this arranges the meshes in a cubical pattern, where the number of visible meshes
+//! varies with the viewing angle. You can choose to run the demo with a spherical pattern that
+//! distributes the meshes evenly.
+//!
+//! To start the demo using the spherical layout run
+//! `cargo run --example many_cubes --release -- sphere`
+
 use bevy::{
     diagnostic::{FrameTimeDiagnosticsPlugin, LogDiagnosticsPlugin},
     math::{DVec2, DVec3},
     prelude::*,
 };
+
 fn main() {
     App::new()
         .add_plugins(DefaultPlugins)
@@ -119,6 +132,7 @@ fn setup(
 // http://extremelearning.com.au/how-to-evenly-distribute-points-on-a-sphere-more-effectively-than-the-canonical-fibonacci-lattice/
 // for details.
 const EPSILON: f64 = 0.36;
+
 fn fibonacci_spiral_on_sphere(golden_ratio: f64, i: usize, n: usize) -> DVec2 {
     DVec2::new(
         2.0 * std::f64::consts::PI * (i as f64 / golden_ratio),
diff --git a/examples/tools/scene_viewer.rs b/examples/tools/scene_viewer.rs
index eceade01f4631..48447c726f63a 100644
--- a/examples/tools/scene_viewer.rs
+++ b/examples/tools/scene_viewer.rs
@@ -1,3 +1,8 @@
+//! A simple way to view glTF models with Bevy.
+//! Just run `cargo run --release --example scene_viewer -- /path/to/model.gltf#Scene0`,
+//! replacing the path as appropriate.
+//! With no arguments it will load the FieldHelmet glTF model from the repository assets subdirectory.
+
 use bevy::{
     asset::{AssetServerSettings, LoadState},
     gltf::Gltf,
@@ -151,6 +156,7 @@ fn start_animation(
         }
     }
 }
+
 fn keyboard_animation_control(
     keyboard_input: Res<Input<KeyCode>>,
     mut animation_player: Query<&mut AnimationPlayer>,
diff --git a/examples/transforms/3d_rotation.rs b/examples/transforms/3d_rotation.rs
index 4afa84e417852..12dbdc33c6fa9 100644
--- a/examples/transforms/3d_rotation.rs
+++ b/examples/transforms/3d_rotation.rs
@@ -1,3 +1,5 @@
+//! Illustrates how to (constantly) rotate an object around an axis
+
 use bevy::prelude::*;
 
 use std::f32::consts::PI;
diff --git a/examples/transforms/global_vs_local_translation.rs b/examples/transforms/global_vs_local_translation.rs
index 25dde970b4f72..1b44d92cb8f27 100644
--- a/examples/transforms/global_vs_local_translation.rs
+++ b/examples/transforms/global_vs_local_translation.rs
@@ -1,3 +1,6 @@
+//! Illustrates the difference between direction of a translation in respect to local object or
+//! global object Transform
+
 use bevy::prelude::*;
 
 // Define a marker for entities that should be changed via their global transform.
@@ -114,9 +117,10 @@ The red cube is moved through its GlobalTransform and thus is unaffected by the
             TextAlignment {
                 horizontal: HorizontalAlign::Left,
                 ..Default::default()
-            }
+            },
         ),
-        ..Default::default()});
+        ..Default::default()
+    });
 }
 
 // This system will move all cubes that are marked as ChangeGlobal according to their global transform.
@@ -146,10 +150,10 @@ fn move_cubes_according_to_local_transform(
 fn update_directional_input(mut direction: ResMut<Direction>, keyboard_input: Res<Input<KeyCode>>) {
     let horizontal_movement = Vec3::X
         * (keyboard_input.pressed(KeyCode::Right) as i32
-            - keyboard_input.pressed(KeyCode::Left) as i32) as f32;
+        - keyboard_input.pressed(KeyCode::Left) as i32) as f32;
     let vertical_movement = Vec3::Y
         * (keyboard_input.pressed(KeyCode::Up) as i32
-            - keyboard_input.pressed(KeyCode::Down) as i32) as f32;
+        - keyboard_input.pressed(KeyCode::Down) as i32) as f32;
     direction.0 = horizontal_movement + vertical_movement;
 }
 
diff --git a/examples/transforms/scale.rs b/examples/transforms/scale.rs
index 09e6a265f28ff..d3770eecdf631 100644
--- a/examples/transforms/scale.rs
+++ b/examples/transforms/scale.rs
@@ -1,3 +1,5 @@
+//! Illustrates how to scale an object in each direction
+
 use bevy::math::Vec3Swizzles;
 use bevy::prelude::*;
 use std::f32::consts::PI;
diff --git a/examples/transforms/transform.rs b/examples/transforms/transform.rs
index e35f43445cbbb..39b5646fed150 100644
--- a/examples/transforms/transform.rs
+++ b/examples/transforms/transform.rs
@@ -1,3 +1,5 @@
+//! Shows multiple transformations of objects
+
 use bevy::prelude::*;
 
 use std::f32::consts::PI;
diff --git a/examples/transforms/translation.rs b/examples/transforms/translation.rs
index e61dc76f25682..54901b2687d90 100644
--- a/examples/transforms/translation.rs
+++ b/examples/transforms/translation.rs
@@ -1,3 +1,5 @@
+//! Illustrates how to move an object along an axis
+
 use bevy::prelude::*;
 
 // Define a struct to keep some information about our entity.
diff --git a/examples/ui/button.rs b/examples/ui/button.rs
index 60269a1f46b7c..b688da04766f8 100644
--- a/examples/ui/button.rs
+++ b/examples/ui/button.rs
@@ -1,7 +1,8 @@
+//! This example illustrates how to create a button that changes color and text based on its
+//! interaction state.
+
 use bevy::{prelude::*, winit::WinitSettings};
 
-/// This example illustrates how to create a button that changes color and text based on its
-/// interaction state.
 fn main() {
     App::new()
         .add_plugins(DefaultPlugins)
diff --git a/examples/ui/font_atlas_debug.rs b/examples/ui/font_atlas_debug.rs
index b598e70c31b54..18b7aa1635113 100644
--- a/examples/ui/font_atlas_debug.rs
+++ b/examples/ui/font_atlas_debug.rs
@@ -1,8 +1,8 @@
+//! This example illustrates how `FontAtlas`'s are populated.
+//! Bevy uses `FontAtlas`'s under the hood to optimize text rendering.
+
 use bevy::{prelude::*, text::FontAtlasSet};
 
-// TODO: This is now broken. See #1243
-/// This example illustrates how `FontAtlas`'s are populated. Bevy uses `FontAtlas`'s under the hood
-/// to optimize text rendering.
 fn main() {
     App::new()
         .init_resource::<State>()
diff --git a/examples/ui/text.rs b/examples/ui/text.rs
index b7d62b5fc52b6..173ac80b47a03 100644
--- a/examples/ui/text.rs
+++ b/examples/ui/text.rs
@@ -1,11 +1,12 @@
+//! This example illustrates how to create UI text and update it in a system. It displays the
+//! current FPS in the top left corner, as well as text that changes colour in the bottom right.
+//! For text within a scene, please see the text2d example.
+
 use bevy::{
     diagnostic::{Diagnostics, FrameTimeDiagnosticsPlugin},
     prelude::*,
 };
 
-/// This example illustrates how to create UI text and update it in a system. It displays the
-/// current FPS in the top left corner, as well as text that changes colour in the bottom right.
-/// For text within a scene, please see the text2d example.
 fn main() {
     App::new()
         .add_plugins(DefaultPlugins)
diff --git a/examples/ui/text_debug.rs b/examples/ui/text_debug.rs
index a40f915214b33..4389f4d228e72 100644
--- a/examples/ui/text_debug.rs
+++ b/examples/ui/text_debug.rs
@@ -1,10 +1,11 @@
+//! This example is for debugging text layout
+
 use bevy::{
     diagnostic::{Diagnostics, FrameTimeDiagnosticsPlugin},
     prelude::*,
     window::PresentMode,
 };
 
-/// This example is for debugging text layout
 fn main() {
     App::new()
         .insert_resource(WindowDescriptor {
diff --git a/examples/ui/ui.rs b/examples/ui/ui.rs
index 30734a87de5de..f99812c95e6f8 100644
--- a/examples/ui/ui.rs
+++ b/examples/ui/ui.rs
@@ -1,10 +1,11 @@
+//! This example illustrates the various features of Bevy UI.
+
 use bevy::{
     input::mouse::{MouseScrollUnit, MouseWheel},
     prelude::*,
     winit::WinitSettings,
 };
 
-/// This example illustrates the various features of Bevy UI.
 fn main() {
     App::new()
         .add_plugins(DefaultPlugins)
diff --git a/examples/window/clear_color.rs b/examples/window/clear_color.rs
index b7813ee2c34d4..d8ba08cbb4175 100644
--- a/examples/window/clear_color.rs
+++ b/examples/window/clear_color.rs
@@ -1,3 +1,5 @@
+//! Creates a solid color window
+
 use bevy::prelude::*;
 
 fn main() {
diff --git a/examples/window/low_power.rs b/examples/window/low_power.rs
index 6ecd9ff4cc463..52a7bc240202f 100644
--- a/examples/window/low_power.rs
+++ b/examples/window/low_power.rs
@@ -1,3 +1,7 @@
+//! This example illustrates how to run a winit window in a reactive, low power mode.
+//! This is useful for making desktop applications, or any other program that doesn't need to be
+//! running the event loop non-stop.
+
 use std::time::Duration;
 
 use bevy::{
@@ -6,9 +10,6 @@ use bevy::{
     winit::WinitSettings,
 };
 
-/// This example illustrates how to run a winit window in a reactive, low power mode. This is useful
-/// for making desktop applications, or any other program that doesn't need to be running the event
-/// loop non-stop.
 fn main() {
     App::new()
         // Continuous rendering for games - bevy's default.
diff --git a/examples/window/multiple_windows.rs b/examples/window/multiple_windows.rs
index a0d168c570881..27844f7dd9bc6 100644
--- a/examples/window/multiple_windows.rs
+++ b/examples/window/multiple_windows.rs
@@ -1,3 +1,5 @@
+//! This example creates a second window and draws a mesh from two different cameras, one in each window
+
 use bevy::{
     core_pipeline::{self, AlphaMask3d, Opaque3d, Transparent3d},
     prelude::*,
@@ -11,7 +13,6 @@ use bevy::{
     window::{CreateWindow, PresentMode, WindowId},
 };
 
-/// This example creates a second window and draws a mesh from two different cameras, one in each window
 fn main() {
     App::new()
         .add_plugins(DefaultPlugins)
diff --git a/examples/window/scale_factor_override.rs b/examples/window/scale_factor_override.rs
index cea0a0f3e80b5..78a9072eae63f 100644
--- a/examples/window/scale_factor_override.rs
+++ b/examples/window/scale_factor_override.rs
@@ -1,6 +1,7 @@
+//! This example illustrates how to customize the default window settings
+
 use bevy::prelude::*;
 
-/// This example illustrates how to customize the default window settings
 fn main() {
     App::new()
         .insert_resource(WindowDescriptor {
diff --git a/examples/window/transparent_window.rs b/examples/window/transparent_window.rs
index 55de3fbf96fe8..a5b11017eb318 100644
--- a/examples/window/transparent_window.rs
+++ b/examples/window/transparent_window.rs
@@ -1,5 +1,6 @@
-/// An example of how to display a window in transparent mode
-/// [Documentation & Platform support.](https://docs.rs/bevy/latest/bevy/prelude/struct.WindowDescriptor.html#structfield.transparent)
+//! An example of how to display a window in transparent mode
+//! [Documentation & Platform support.](https://docs.rs/bevy/latest/bevy/prelude/struct.WindowDescriptor.html#structfield.transparent)
+
 use bevy::{prelude::*, window::WindowDescriptor};
 
 fn main() {
diff --git a/examples/window/window_settings.rs b/examples/window/window_settings.rs
index 85beb371e2428..7d45b68e6e2ba 100644
--- a/examples/window/window_settings.rs
+++ b/examples/window/window_settings.rs
@@ -1,6 +1,7 @@
+//! This example illustrates how to customize the default window settings
+
 use bevy::{prelude::*, window::PresentMode};
 
-/// This example illustrates how to customize the default window settings
 fn main() {
     App::new()
         .insert_resource(WindowDescriptor {

From 445327c28ee27cf793664bdcebb3fe3f5d646bb4 Mon Sep 17 00:00:00 2001
From: Mark Schmale <masch@masch.it>
Date: Sun, 17 Apr 2022 13:27:01 +0200
Subject: [PATCH 13/23] Some small changes to the examples README.md

re-sorted two groups alphabetically.
---
 examples/README.md | 13 +++++++------
 1 file changed, 7 insertions(+), 6 deletions(-)

diff --git a/examples/README.md b/examples/README.md
index 7e69d518582c9..1b7ccda206309 100644
--- a/examples/README.md
+++ b/examples/README.md
@@ -74,6 +74,7 @@ git checkout v0.4.0
 
 <!-- MD026 - Hello, World! looks better with the ! -->
 <!-- markdownlint-disable-next-line MD026 -->
+
 ## Hello, World!
 
 Example | File | Description
@@ -241,14 +242,14 @@ Example | File | Description
 
 Example | File | Description
 --- | --- | ---
-`custom_vertex_attribute` | [`shader/custom_vertex_attribute.rs`](./shader/custom_vertex_attribute.rs) | Illustrates creating a custom shader material that reads a mesh's custom vertex attribute.
-`shader_material` | [`shader/shader_material.rs`](./shader/shader_material.rs) | Illustrates creating a custom material and a shader that uses it
-`shader_material_screenspace_texture` | [`shader/shader_material_screenspace_texture.rs`](./shader/shader_material_screenspace_texture.rs) | A custom shader sampling a texture with view-independent UV coordinates
-`shader_material_glsl` | [`shader/shader_material_glsl.rs`](./shader/shader_material_glsl.rs) | A custom shader using the GLSL shading language.
-`shader_instancing` | [`shader/shader_instancing.rs`](./shader/shader_instancing.rs) | A custom shader showing off rendering a mesh multiple times in one draw call.
 `animate_shader` | [`shader/animate_shader.rs`](./shader/animate_shader.rs) | Shows how to pass changing data like the time since startup into a shader.
 `compute_shader_game_of_life` | [`shader/compute_shader_game_of_life.rs`](./shader/compute_shader_game_of_life.rs) | A compute shader simulating Conway's Game of Life
+`custom_vertex_attribute` | [`shader/custom_vertex_attribute.rs`](./shader/custom_vertex_attribute.rs) | Illustrates creating a custom shader material that reads a mesh's custom vertex attribute.
 `shader_defs` | [`shader/shader_defs.rs`](./shader/shader_defs.rs) | Demonstrates creating a custom material that uses "shaders defs" (a tool to selectively toggle parts of a shader)
+`shader_instancing` | [`shader/shader_instancing.rs`](./shader/shader_instancing.rs) | A custom shader showing off rendering a mesh multiple times in one draw call.
+`shader_material` | [`shader/shader_material.rs`](./shader/shader_material.rs) | Illustrates creating a custom material and a shader that uses it
+`shader_material_glsl` | [`shader/shader_material_glsl.rs`](./shader/shader_material_glsl.rs) | A custom shader using the GLSL shading language.
+`shader_material_screenspace_texture` | [`shader/shader_material_screenspace_texture.rs`](./shader/shader_material_screenspace_texture.rs) | A custom shader sampling a texture with view-independent UV coordinates
 
 ## Stress Tests
 
@@ -285,8 +286,8 @@ Example | File | Description
 
 Example | File | Description
 --- | --- | ---
-`global_vs_local_translation` | [`transforms/global_vs_local_translation.rs`](./transforms/global_vs_local_translation.rs) | Illustrates the difference between direction of a translation in respect to local object or global object Transform
 `3d_rotation` | [`transforms/3d_rotation.rs`](./transforms/3d_rotation.rs) | Illustrates how to (constantly) rotate an object around an axis
+`global_vs_local_translation` | [`transforms/global_vs_local_translation.rs`](./transforms/global_vs_local_translation.rs) | Illustrates the difference between direction of a translation in respect to local object or global object Transform
 `scale` | [`transforms/scale.rs`](./transforms/scale.rs) | Illustrates how to scale an object in each direction
 `transform` | [`transforms/transfrom.rs`](./transforms/transform.rs) | Shows multiple transformations of objects
 `translation` | [`transforms/translation.rs`](./transforms/translation.rs) | Illustrates how to move an object along an axis

From 1b3e16b3e19bcfb5c54b45a201ca3dc9e209a0f5 Mon Sep 17 00:00:00 2001
From: Mark Schmale <masch@masch.it>
Date: Sun, 17 Apr 2022 13:41:45 +0200
Subject: [PATCH 14/23] Last missing blocks after rebase.

---
 examples/3d/two_passes.rs                | 4 ++++
 examples/animation/animated_transform.rs | 6 ++++--
 examples/app/logs.rs                     | 1 +
 examples/stress_tests/many_lights.rs     | 3 +++
 4 files changed, 12 insertions(+), 2 deletions(-)

diff --git a/examples/3d/two_passes.rs b/examples/3d/two_passes.rs
index ecf161506fcb2..0803bbe4b9a2f 100644
--- a/examples/3d/two_passes.rs
+++ b/examples/3d/two_passes.rs
@@ -1,3 +1,6 @@
+//! Shows how to render multiple passes to the same window, useful for rendering different views
+//! or drawing an object on top regardless of depth
+
 use bevy::{
     core_pipeline::{draw_3d_graph, node, AlphaMask3d, Opaque3d, Transparent3d},
     prelude::*,
@@ -68,6 +71,7 @@ fn extract_first_pass_camera_phases(
         ));
     }
 }
+
 // A node for the first pass camera that runs draw_3d_graph with this camera.
 struct FirstPassCameraDriver {
     query: QueryState<Entity, With<FirstPassCamera>>,
diff --git a/examples/animation/animated_transform.rs b/examples/animation/animated_transform.rs
index 5084253615ec7..5327482b4dde5 100644
--- a/examples/animation/animated_transform.rs
+++ b/examples/animation/animated_transform.rs
@@ -1,3 +1,5 @@
+//! Create and play an animation defined by code that operates on the `Transform` component.
+
 use std::f32::consts::{FRAC_PI_2, PI};
 
 use bevy::prelude::*;
@@ -134,8 +136,8 @@ fn setup(
                         material: materials.add(Color::rgb(0.3, 0.9, 0.3).into()),
                         ..default()
                     })
-                    // Add the Name component
-                    .insert(satellite);
+                        // Add the Name component
+                        .insert(satellite);
                 });
         });
 }
diff --git a/examples/app/logs.rs b/examples/app/logs.rs
index ff4dfc151cd64..507b625d30f75 100644
--- a/examples/app/logs.rs
+++ b/examples/app/logs.rs
@@ -1,4 +1,5 @@
 //! This example illustrates how to use logs in bevy
+
 use bevy::prelude::*;
 
 fn main() {
diff --git a/examples/stress_tests/many_lights.rs b/examples/stress_tests/many_lights.rs
index 6fe6f91297e8a..d0b765d15ddca 100644
--- a/examples/stress_tests/many_lights.rs
+++ b/examples/stress_tests/many_lights.rs
@@ -1,3 +1,6 @@
+//! Simple benchmark to test rendering many point lights.
+//! Run with `WGPU_SETTINGS_PRIO=webgl2` to restrict to uniform buffers and max 256 lights.
+
 use bevy::{
     diagnostic::{FrameTimeDiagnosticsPlugin, LogDiagnosticsPlugin},
     math::{DVec2, DVec3},

From 7b18e712ea1cfb668faf2028f7ad8c387ad14fa0 Mon Sep 17 00:00:00 2001
From: Mark Schmale <masch@masch.it>
Date: Sun, 17 Apr 2022 14:18:33 +0200
Subject: [PATCH 15/23] ran cargo fmt --all to fix whatever the IDE auto format
 broke.

---
 examples/animation/animated_transform.rs           | 4 ++--
 examples/asset/custom_asset_io.rs                  | 2 +-
 examples/games/alien_cake_addict.rs                | 2 +-
 examples/shader/animate_shader.rs                  | 2 +-
 examples/shader/compute_shader_game_of_life.rs     | 4 ++--
 examples/transforms/global_vs_local_translation.rs | 4 ++--
 6 files changed, 9 insertions(+), 9 deletions(-)

diff --git a/examples/animation/animated_transform.rs b/examples/animation/animated_transform.rs
index 5327482b4dde5..fb9454ae41f44 100644
--- a/examples/animation/animated_transform.rs
+++ b/examples/animation/animated_transform.rs
@@ -136,8 +136,8 @@ fn setup(
                         material: materials.add(Color::rgb(0.3, 0.9, 0.3).into()),
                         ..default()
                     })
-                        // Add the Name component
-                        .insert(satellite);
+                    // Add the Name component
+                    .insert(satellite);
                 });
         });
 }
diff --git a/examples/asset/custom_asset_io.rs b/examples/asset/custom_asset_io.rs
index dcf62c5ab55d6..c49b653a43b37 100644
--- a/examples/asset/custom_asset_io.rs
+++ b/examples/asset/custom_asset_io.rs
@@ -25,7 +25,7 @@ impl AssetIo for CustomAssetIo {
     fn read_directory(
         &self,
         path: &Path,
-    ) -> Result<Box<dyn Iterator<Item=PathBuf>>, AssetIoError> {
+    ) -> Result<Box<dyn Iterator<Item = PathBuf>>, AssetIoError> {
         info!("read_directory({:?})", path);
         self.0.read_directory(path)
     }
diff --git a/examples/games/alien_cake_addict.rs b/examples/games/alien_cake_addict.rs
index 07ef9bc64ee56..08f69f59cb538 100644
--- a/examples/games/alien_cake_addict.rs
+++ b/examples/games/alien_cake_addict.rs
@@ -86,7 +86,7 @@ fn setup_cameras(mut commands: Commands, mut game: ResMut<Game>) {
             2.0 * BOARD_SIZE_J as f32 / 3.0,
             BOARD_SIZE_J as f32 / 2.0 - 0.5,
         )
-            .looking_at(game.camera_is_focus, Vec3::Y),
+        .looking_at(game.camera_is_focus, Vec3::Y),
         ..default()
     });
     commands.spawn_bundle(UiCameraBundle::default());
diff --git a/examples/shader/animate_shader.rs b/examples/shader/animate_shader.rs
index 0bcc860bf1ebd..dd46d6293d985 100644
--- a/examples/shader/animate_shader.rs
+++ b/examples/shader/animate_shader.rs
@@ -88,7 +88,7 @@ fn extract_custom_material(
 ) {
     let mut values = Vec::with_capacity(*previous_len);
     for entity in query.iter_mut() {
-        values.push((entity, (CustomMaterial, )));
+        values.push((entity, (CustomMaterial,)));
     }
     *previous_len = values.len();
     commands.insert_or_spawn_batch(values);
diff --git a/examples/shader/compute_shader_game_of_life.rs b/examples/shader/compute_shader_game_of_life.rs
index d2ffb80c1ba98..b019fa5739a80 100644
--- a/examples/shader/compute_shader_game_of_life.rs
+++ b/examples/shader/compute_shader_game_of_life.rs
@@ -183,14 +183,14 @@ impl render_graph::Node for GameOfLifeNode {
         match self.state {
             GameOfLifeState::Loading => {
                 if let CachedPipelineState::Ok(_) =
-                pipeline_cache.get_compute_pipeline_state(pipeline.init_pipeline)
+                    pipeline_cache.get_compute_pipeline_state(pipeline.init_pipeline)
                 {
                     self.state = GameOfLifeState::Init
                 }
             }
             GameOfLifeState::Init => {
                 if let CachedPipelineState::Ok(_) =
-                pipeline_cache.get_compute_pipeline_state(pipeline.update_pipeline)
+                    pipeline_cache.get_compute_pipeline_state(pipeline.update_pipeline)
                 {
                     self.state = GameOfLifeState::Update
                 }
diff --git a/examples/transforms/global_vs_local_translation.rs b/examples/transforms/global_vs_local_translation.rs
index 1b44d92cb8f27..23d4a35272a3f 100644
--- a/examples/transforms/global_vs_local_translation.rs
+++ b/examples/transforms/global_vs_local_translation.rs
@@ -150,10 +150,10 @@ fn move_cubes_according_to_local_transform(
 fn update_directional_input(mut direction: ResMut<Direction>, keyboard_input: Res<Input<KeyCode>>) {
     let horizontal_movement = Vec3::X
         * (keyboard_input.pressed(KeyCode::Right) as i32
-        - keyboard_input.pressed(KeyCode::Left) as i32) as f32;
+            - keyboard_input.pressed(KeyCode::Left) as i32) as f32;
     let vertical_movement = Vec3::Y
         * (keyboard_input.pressed(KeyCode::Up) as i32
-        - keyboard_input.pressed(KeyCode::Down) as i32) as f32;
+            - keyboard_input.pressed(KeyCode::Down) as i32) as f32;
     direction.0 = horizontal_movement + vertical_movement;
 }
 

From c1b1da023ec101d491d4e0619fa4eb30dd89ca52 Mon Sep 17 00:00:00 2001
From: Mark Schmale <masch@masch.it>
Date: Sun, 17 Apr 2022 14:20:05 +0200
Subject: [PATCH 16/23] re-enable the markdownlint-ignore

---
 examples/README.md | 1 -
 1 file changed, 1 deletion(-)

diff --git a/examples/README.md b/examples/README.md
index 1b7ccda206309..54852962b0975 100644
--- a/examples/README.md
+++ b/examples/README.md
@@ -74,7 +74,6 @@ git checkout v0.4.0
 
 <!-- MD026 - Hello, World! looks better with the ! -->
 <!-- markdownlint-disable-next-line MD026 -->
-
 ## Hello, World!
 
 Example | File | Description

From 583acd457587dd844227a23217078a188d38423c Mon Sep 17 00:00:00 2001
From: Mark Schmale <masch@masch.it>
Date: Sun, 17 Apr 2022 14:54:45 +0200
Subject: [PATCH 17/23] fixed some clippy md complaints in the new doc blocks

---
 examples/ecs/system_chaining.rs | 2 +-
 examples/tools/scene_viewer.rs  | 2 +-
 2 files changed, 2 insertions(+), 2 deletions(-)

diff --git a/examples/ecs/system_chaining.rs b/examples/ecs/system_chaining.rs
index 6bab5a46c38f5..cb632d2089821 100644
--- a/examples/ecs/system_chaining.rs
+++ b/examples/ecs/system_chaining.rs
@@ -1,4 +1,4 @@
-//! Illustrates how to use States to control transitioning from a Menu state to an InGame state
+//! Illustrates how to use States to control transitioning from a Menu state to an `InGame` state
 
 use anyhow::Result;
 use bevy::prelude::*;
diff --git a/examples/tools/scene_viewer.rs b/examples/tools/scene_viewer.rs
index 48447c726f63a..e964a1faaa54f 100644
--- a/examples/tools/scene_viewer.rs
+++ b/examples/tools/scene_viewer.rs
@@ -1,7 +1,7 @@
 //! A simple way to view glTF models with Bevy.
 //! Just run `cargo run --release --example scene_viewer -- /path/to/model.gltf#Scene0`,
 //! replacing the path as appropriate.
-//! With no arguments it will load the FieldHelmet glTF model from the repository assets subdirectory.
+//! With no arguments it will load the `FieldHelmet` glTF model from the repository assets subdirectory.
 
 use bevy::{
     asset::{AssetServerSettings, LoadState},

From f9fd8b9de6f0696f5905b0127b2003626370170a Mon Sep 17 00:00:00 2001
From: Mark Schmale <masch@masch.it>
Date: Mon, 18 Apr 2022 11:57:18 +0200
Subject: [PATCH 18/23] remove unnecessary argument separator in `cargo run`
 calls

---
 examples/README.md                           | 2 +-
 examples/stress_tests/many_cubes.rs          | 2 +-
 examples/stress_tests/transform_hierarchy.rs | 2 +-
 examples/tools/scene_viewer.rs               | 2 +-
 4 files changed, 4 insertions(+), 4 deletions(-)

diff --git a/examples/README.md b/examples/README.md
index 54852962b0975..b27fa3dd55d93 100644
--- a/examples/README.md
+++ b/examples/README.md
@@ -279,7 +279,7 @@ Example | File | Description
 
 Example | File | Description
 --- | --- | ---
-`scene_viewer` | [`tools/scene_viewer.rs`](./tools/scene_viewer.rs) | A simple way to view glTF models with Bevy. Just run `cargo run --release --example scene_viewer -- /path/to/model.gltf#Scene0`, replacing the path as appropriate. With no arguments it will load the FieldHelmet glTF model from the repository assets subdirectory.
+`scene_viewer` | [`tools/scene_viewer.rs`](./tools/scene_viewer.rs) | A simple way to view glTF models with Bevy. Just run `cargo run --release --example scene_viewer /path/to/model.gltf#Scene0`, replacing the path as appropriate. With no arguments it will load the FieldHelmet glTF model from the repository assets subdirectory.
 
 ## Transforms
 
diff --git a/examples/stress_tests/many_cubes.rs b/examples/stress_tests/many_cubes.rs
index 3405bf1d1c061..0c57f290cf797 100644
--- a/examples/stress_tests/many_cubes.rs
+++ b/examples/stress_tests/many_cubes.rs
@@ -8,7 +8,7 @@
 //! distributes the meshes evenly.
 //!
 //! To start the demo using the spherical layout run
-//! `cargo run --example many_cubes --release -- sphere`
+//! `cargo run --example many_cubes --release sphere`
 
 use bevy::{
     diagnostic::{FrameTimeDiagnosticsPlugin, LogDiagnosticsPlugin},
diff --git a/examples/stress_tests/transform_hierarchy.rs b/examples/stress_tests/transform_hierarchy.rs
index 360f992f129f6..8dec698f95f42 100644
--- a/examples/stress_tests/transform_hierarchy.rs
+++ b/examples/stress_tests/transform_hierarchy.rs
@@ -3,7 +3,7 @@
 //! Running this example:
 //!
 //! ```
-//! cargo r --release --example transform_hierarchy -- <configuration name>
+//! cargo r --release --example transform_hierarchy <configuration name>
 //! ```
 //!
 //! | Configuration        | Description                                                       |
diff --git a/examples/tools/scene_viewer.rs b/examples/tools/scene_viewer.rs
index e964a1faaa54f..fb900ada01e28 100644
--- a/examples/tools/scene_viewer.rs
+++ b/examples/tools/scene_viewer.rs
@@ -1,5 +1,5 @@
 //! A simple way to view glTF models with Bevy.
-//! Just run `cargo run --release --example scene_viewer -- /path/to/model.gltf#Scene0`,
+//! Just run `cargo run --release --example scene_viewer /path/to/model.gltf#Scene0`,
 //! replacing the path as appropriate.
 //! With no arguments it will load the `FieldHelmet` glTF model from the repository assets subdirectory.
 

From 8313bacc8304921c6201a159de7da3f9b472817e Mon Sep 17 00:00:00 2001
From: Mark Schmale <masch@masch.it>
Date: Mon, 18 Apr 2022 12:00:44 +0200
Subject: [PATCH 19/23] some rewording, the old one was missing words and
 therefore meaning.

---
 examples/stress_tests/many_cubes.rs | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/examples/stress_tests/many_cubes.rs b/examples/stress_tests/many_cubes.rs
index 0c57f290cf797..e2d2befd94ed2 100644
--- a/examples/stress_tests/many_cubes.rs
+++ b/examples/stress_tests/many_cubes.rs
@@ -1,6 +1,6 @@
 //! Simple benchmark to test per-entity draw overhead
 //!
-//! To a realistic performance result, run this in release mode.
+//! To measure performance realistically, be sure to run this in release mode.
 //! `cargo run --example many_cubes --release`
 //!
 //! Per default this arranges the meshes in a cubical pattern, where the number of visible meshes

From 64d11cb7faf5ddcff493483b7b870a0049455444 Mon Sep 17 00:00:00 2001
From: Mark Schmale <masch@masch.it>
Date: Mon, 18 Apr 2022 12:16:58 +0200
Subject: [PATCH 20/23] add some detail.

---
 examples/app/headless_defaults.rs              | 1 +
 examples/shader/compute_shader_game_of_life.rs | 2 ++
 2 files changed, 3 insertions(+)

diff --git a/examples/app/headless_defaults.rs b/examples/app/headless_defaults.rs
index e640b01ffba36..59dec5453ab63 100644
--- a/examples/app/headless_defaults.rs
+++ b/examples/app/headless_defaults.rs
@@ -1,4 +1,5 @@
 //! An application that runs with default plugins, but without an actual renderer
+//! This can be very useful for integration tests or CI.
 
 use bevy::{prelude::*, render::settings::WgpuSettings};
 
diff --git a/examples/shader/compute_shader_game_of_life.rs b/examples/shader/compute_shader_game_of_life.rs
index b019fa5739a80..7049ce0212736 100644
--- a/examples/shader/compute_shader_game_of_life.rs
+++ b/examples/shader/compute_shader_game_of_life.rs
@@ -1,4 +1,6 @@
 //! A compute shader simulating Conway's Game of Life
+//! Compute shaders use the GPU for computing arbitrary information, that may be independent of what
+//! is rendered to the screen.
 
 use bevy::{
     core_pipeline::node::MAIN_PASS_DEPENDENCIES,

From dad654a316dcb707f20f7349f853a6bced067560 Mon Sep 17 00:00:00 2001
From: Mark Schmale <masch@masch.it>
Date: Sun, 1 May 2022 13:54:07 +0200
Subject: [PATCH 21/23] Add/fix some punctuation.

---
 examples/2d/mesh2d_manual.rs                         |  6 +++---
 examples/2d/rotation.rs                              |  2 +-
 examples/2d/text2d.rs                                |  2 +-
 examples/2d/texture_atlas.rs                         |  2 +-
 examples/3d/lighting.rs                              |  2 +-
 examples/3d/load_gltf.rs                             |  2 +-
 examples/3d/orthographic.rs                          |  2 +-
 examples/3d/parenting.rs                             |  4 ++--
 examples/3d/render_to_texture.rs                     |  2 +-
 examples/3d/shadow_biases.rs                         |  2 +-
 examples/3d/shadow_caster_receiver.rs                |  2 +-
 examples/3d/texture.rs                               |  2 +-
 examples/3d/two_passes.rs                            |  2 +-
 examples/3d/update_gltf_scene.rs                     |  2 +-
 examples/3d/wireframe.rs                             |  2 +-
 examples/app/empty_defaults.rs                       |  2 +-
 examples/app/headless.rs                             |  2 +-
 examples/app/logs.rs                                 |  2 +-
 examples/app/return_after_run.rs                     |  2 +-
 examples/app/without_winit.rs                        |  2 +-
 examples/asset/asset_loading.rs                      |  2 +-
 examples/asset/custom_asset.rs                       |  2 +-
 examples/asset/custom_asset_io.rs                    |  2 +-
 .../async_tasks/external_source_external_thread.rs   |  2 +-
 examples/audio/audio.rs                              |  2 +-
 examples/audio/audio_control.rs                      |  2 +-
 examples/diagnostics/custom_diagnostic.rs            | 12 ++++++------
 examples/diagnostics/log_diagnostics.rs              |  2 +-
 examples/ecs/component_change_detection.rs           |  2 +-
 examples/ecs/fixed_timestep.rs                       |  2 +-
 examples/ecs/hierarchy.rs                            |  2 +-
 examples/ecs/parallel_query.rs                       |  2 +-
 examples/ecs/startup_system.rs                       |  2 +-
 examples/ecs/system_chaining.rs                      |  2 +-
 examples/ecs/system_param.rs                         |  2 +-
 examples/ecs/timers.rs                               |  2 +-
 examples/games/alien_cake_addict.rs                  |  2 +-
 examples/games/breakout.rs                           |  2 +-
 examples/input/gamepad_input.rs                      |  2 +-
 examples/input/gamepad_input_events.rs               |  2 +-
 examples/input/keyboard_input.rs                     |  2 +-
 examples/input/keyboard_input_events.rs              |  2 +-
 examples/input/keyboard_modifiers.rs                 |  2 +-
 examples/input/mouse_grab.rs                         |  2 +-
 examples/input/mouse_input.rs                        |  2 +-
 examples/input/mouse_input_events.rs                 |  2 +-
 examples/input/touch_input.rs                        |  2 +-
 examples/input/touch_input_events.rs                 |  2 +-
 examples/reflection/generic_reflection.rs            |  2 +-
 examples/reflection/reflection_types.rs              |  2 +-
 examples/reflection/trait_reflection.rs              |  2 +-
 examples/scene/scene.rs                              |  2 +-
 examples/shader/compute_shader_game_of_life.rs       |  2 +-
 examples/shader/shader_defs.rs                       |  2 +-
 examples/shader/shader_material.rs                   |  2 +-
 .../shader/shader_material_screenspace_texture.rs    |  2 +-
 examples/stress_tests/many_cubes.rs                  |  2 +-
 examples/transforms/3d_rotation.rs                   |  2 +-
 examples/transforms/global_vs_local_translation.rs   |  2 +-
 examples/transforms/scale.rs                         |  2 +-
 examples/transforms/transform.rs                     |  2 +-
 examples/transforms/translation.rs                   |  2 +-
 examples/ui/text_debug.rs                            |  2 +-
 examples/window/clear_color.rs                       |  2 +-
 examples/window/multiple_windows.rs                  |  2 +-
 examples/window/scale_factor_override.rs             |  2 +-
 examples/window/transparent_window.rs                |  2 +-
 examples/window/window_settings.rs                   |  2 +-
 68 files changed, 76 insertions(+), 76 deletions(-)

diff --git a/examples/2d/mesh2d_manual.rs b/examples/2d/mesh2d_manual.rs
index c6367b1abebe4..0fea936b4f44f 100644
--- a/examples/2d/mesh2d_manual.rs
+++ b/examples/2d/mesh2d_manual.rs
@@ -1,7 +1,7 @@
-//! This example shows how to manually render 2d items using "mid level render apis" with  a custom
+//! This example shows how to manually render 2d items using "mid level render apis" with a custom
 //! pipeline for 2d meshes.
-//! It doesn't use the [`Material2d`] abstraction, but changes the vertex buffer to include vertex color
-//! Check out the "mesh2d" example for simpler / higher level 2d meshes
+//! It doesn't use the [`Material2d`] abstraction, but changes the vertex buffer to include vertex color.
+//! Check out the "mesh2d" example for simpler / higher level 2d meshes.
 
 use bevy::{
     core_pipeline::Transparent2d,
diff --git a/examples/2d/rotation.rs b/examples/2d/rotation.rs
index 46189fc5b639c..73313ea53ad90 100644
--- a/examples/2d/rotation.rs
+++ b/examples/2d/rotation.rs
@@ -1,4 +1,4 @@
-//! Demonstrates rotating entities in 2D with quaternions.
+//! Demonstrates rotating entities in 2D using quaternions.
 
 use bevy::{
     core::FixedTimestep,
diff --git a/examples/2d/text2d.rs b/examples/2d/text2d.rs
index b43b627155379..bb7c9087696a0 100644
--- a/examples/2d/text2d.rs
+++ b/examples/2d/text2d.rs
@@ -1,4 +1,4 @@
-//! Example to show text rendering with moving, rotating and scaling text.
+//! Shows text rendering with moving, rotating and scaling text.
 //!
 //! Note that this uses [`Text2dBundle`] to display text alongside your other entities in a 2D scene.
 //!
diff --git a/examples/2d/texture_atlas.rs b/examples/2d/texture_atlas.rs
index cde80e51ec2e8..45f7a24606b97 100644
--- a/examples/2d/texture_atlas.rs
+++ b/examples/2d/texture_atlas.rs
@@ -1,5 +1,5 @@
 //! In this example we generate a new texture atlas (sprite sheet) from a folder containing
-//! individual sprites
+//! individual sprites.
 
 use bevy::{asset::LoadState, prelude::*};
 
diff --git a/examples/3d/lighting.rs b/examples/3d/lighting.rs
index 2e00bb4307f74..3905ae8d47e15 100644
--- a/examples/3d/lighting.rs
+++ b/examples/3d/lighting.rs
@@ -1,4 +1,4 @@
-//! Illustrates various lighting options in a simple scene
+//! Illustrates various lighting options in a simple scene.
 
 use bevy::prelude::*;
 
diff --git a/examples/3d/load_gltf.rs b/examples/3d/load_gltf.rs
index 683ba3bd3d461..c8a6047d997af 100644
--- a/examples/3d/load_gltf.rs
+++ b/examples/3d/load_gltf.rs
@@ -1,4 +1,4 @@
-//! Loads and renders a gltf file as a scene
+//! Loads and renders a glTF file as a scene.
 
 use bevy::prelude::*;
 
diff --git a/examples/3d/orthographic.rs b/examples/3d/orthographic.rs
index fbf560e9bee9c..5cdd163829931 100644
--- a/examples/3d/orthographic.rs
+++ b/examples/3d/orthographic.rs
@@ -1,4 +1,4 @@
-//! Shows how to create a 3D orthographic view (for isometric-look games or CAD applications)
+//! Shows how to create a 3D orthographic view (for isometric-look games or CAD applications).
 
 use bevy::prelude::*;
 
diff --git a/examples/3d/parenting.rs b/examples/3d/parenting.rs
index 9a46112d981f6..5180b20c7a086 100644
--- a/examples/3d/parenting.rs
+++ b/examples/3d/parenting.rs
@@ -1,5 +1,5 @@
-//! This example illustrates how to create parent->child relationships between entities how parent
-//! transforms are propagated to their descendants
+//! Illustrates how to create parent->child relationships between entities how parent transforms
+//! are propagated to their descendants.
 
 use bevy::prelude::*;
 
diff --git a/examples/3d/render_to_texture.rs b/examples/3d/render_to_texture.rs
index 505cdf1fac80f..9d71e09ea24df 100644
--- a/examples/3d/render_to_texture.rs
+++ b/examples/3d/render_to_texture.rs
@@ -1,4 +1,4 @@
-//! Shows how to render to a texture, useful for mirrors, UI, or exporting images
+//! Shows how to render to a texture, useful for mirrors, UI, or exporting images.
 
 use bevy::{
     core_pipeline::{
diff --git a/examples/3d/shadow_biases.rs b/examples/3d/shadow_biases.rs
index 4954a3131ecbb..2f5e7adb306f8 100644
--- a/examples/3d/shadow_biases.rs
+++ b/examples/3d/shadow_biases.rs
@@ -1,4 +1,4 @@
-//! Demonstrates how shadow biases affect shadows in a 3d scene
+//! Demonstrates how shadow biases affect shadows in a 3d scene.
 
 use bevy::{input::mouse::MouseMotion, prelude::*};
 
diff --git a/examples/3d/shadow_caster_receiver.rs b/examples/3d/shadow_caster_receiver.rs
index 7921554a7290c..c58994ce5b479 100644
--- a/examples/3d/shadow_caster_receiver.rs
+++ b/examples/3d/shadow_caster_receiver.rs
@@ -1,4 +1,4 @@
-//! Demonstrates how to prevent meshes from casting/receiving shadows in a 3d scene
+//! Demonstrates how to prevent meshes from casting/receiving shadows in a 3d scene.
 
 use bevy::{
     pbr::{NotShadowCaster, NotShadowReceiver},
diff --git a/examples/3d/texture.rs b/examples/3d/texture.rs
index 13368dd2dd522..9a0e44d93fcd0 100644
--- a/examples/3d/texture.rs
+++ b/examples/3d/texture.rs
@@ -1,4 +1,4 @@
-//! This example shows various ways to configure texture materials in 3D
+//! This example shows various ways to configure texture materials in 3D.
 
 use bevy::prelude::*;
 
diff --git a/examples/3d/two_passes.rs b/examples/3d/two_passes.rs
index 0803bbe4b9a2f..e9c5a64f235ae 100644
--- a/examples/3d/two_passes.rs
+++ b/examples/3d/two_passes.rs
@@ -1,5 +1,5 @@
 //! Shows how to render multiple passes to the same window, useful for rendering different views
-//! or drawing an object on top regardless of depth
+//! or drawing an object on top regardless of depth.
 
 use bevy::{
     core_pipeline::{draw_3d_graph, node, AlphaMask3d, Opaque3d, Transparent3d},
diff --git a/examples/3d/update_gltf_scene.rs b/examples/3d/update_gltf_scene.rs
index 24eae1e50d3df..d876323648557 100644
--- a/examples/3d/update_gltf_scene.rs
+++ b/examples/3d/update_gltf_scene.rs
@@ -1,5 +1,5 @@
 //! Update a scene from a gltf file, either by spawning the scene as a child of another entity,
-//! or by accessing the entities of the scene
+//! or by accessing the entities of the scene.
 
 use bevy::{prelude::*, scene::InstanceId};
 
diff --git a/examples/3d/wireframe.rs b/examples/3d/wireframe.rs
index 957eeaee853a7..df36a1218d118 100644
--- a/examples/3d/wireframe.rs
+++ b/examples/3d/wireframe.rs
@@ -1,4 +1,4 @@
-//! Showcases wireframe rendering
+//! Showcases wireframe rendering.
 
 use bevy::{
     pbr::wireframe::{Wireframe, WireframeConfig, WireframePlugin},
diff --git a/examples/app/empty_defaults.rs b/examples/app/empty_defaults.rs
index 35950bbd6d705..445ed9fa3ad0d 100644
--- a/examples/app/empty_defaults.rs
+++ b/examples/app/empty_defaults.rs
@@ -1,4 +1,4 @@
-//! An empty application with default plugins
+//! An empty application with default plugins.
 
 use bevy::prelude::*;
 
diff --git a/examples/app/headless.rs b/examples/app/headless.rs
index 921bc1c16d84b..2b3451647ee19 100644
--- a/examples/app/headless.rs
+++ b/examples/app/headless.rs
@@ -1,6 +1,6 @@
 //! This example only enables a minimal set of plugins required for bevy to run.
 //! You can also completely remove rendering / windowing Plugin code from bevy
-//! by making your import look like this in your Cargo.toml
+//! by making your import look like this in your Cargo.toml.
 //!
 //! [dependencies]
 //! bevy = { version = "*", default-features = false }
diff --git a/examples/app/logs.rs b/examples/app/logs.rs
index 507b625d30f75..029637b608eef 100644
--- a/examples/app/logs.rs
+++ b/examples/app/logs.rs
@@ -1,4 +1,4 @@
-//! This example illustrates how to use logs in bevy
+//! This example illustrates how to use logs in bevy.
 
 use bevy::prelude::*;
 
diff --git a/examples/app/return_after_run.rs b/examples/app/return_after_run.rs
index fa88a3af668a3..813a563143a6b 100644
--- a/examples/app/return_after_run.rs
+++ b/examples/app/return_after_run.rs
@@ -1,4 +1,4 @@
-//! Show how to return to main after the Bevy app has exited
+//! Show how to return to main after the Bevy app has exited.
 
 use bevy::{prelude::*, winit::WinitSettings};
 
diff --git a/examples/app/without_winit.rs b/examples/app/without_winit.rs
index 637b9713f2d7b..1339509725fb7 100644
--- a/examples/app/without_winit.rs
+++ b/examples/app/without_winit.rs
@@ -1,4 +1,4 @@
-//! Create an application without winit (runs single time, no event loop)
+//! Create an application without winit (runs single time, no event loop).
 
 use bevy::prelude::*;
 use bevy::winit::WinitPlugin;
diff --git a/examples/asset/asset_loading.rs b/examples/asset/asset_loading.rs
index 39a08e7063b8f..e5693f4ddc60e 100644
--- a/examples/asset/asset_loading.rs
+++ b/examples/asset/asset_loading.rs
@@ -1,4 +1,4 @@
-//! This example illustrates various ways to load assets
+//! This example illustrates various ways to load assets.
 
 use bevy::prelude::*;
 
diff --git a/examples/asset/custom_asset.rs b/examples/asset/custom_asset.rs
index 9df98e9d9aa2a..34698b57899ec 100644
--- a/examples/asset/custom_asset.rs
+++ b/examples/asset/custom_asset.rs
@@ -1,4 +1,4 @@
-//! Implements a custom asset loader
+//! Implements a custom asset loader.
 
 use bevy::{
     asset::{AssetLoader, LoadContext, LoadedAsset},
diff --git a/examples/asset/custom_asset_io.rs b/examples/asset/custom_asset_io.rs
index c49b653a43b37..2763a01a19e10 100644
--- a/examples/asset/custom_asset_io.rs
+++ b/examples/asset/custom_asset_io.rs
@@ -1,4 +1,4 @@
-//! Implements a custom asset io loader
+//! Implements a custom asset io loader.
 //! An [`AssetIo`] load is what the assert server uses to read the raw bytes of assets.
 //! It does not know anything about the asset formats, only how to talk the underlying storage.
 
diff --git a/examples/async_tasks/external_source_external_thread.rs b/examples/async_tasks/external_source_external_thread.rs
index 7be6624735f84..2cb0c04b50395 100644
--- a/examples/async_tasks/external_source_external_thread.rs
+++ b/examples/async_tasks/external_source_external_thread.rs
@@ -1,4 +1,4 @@
-//! How to use an external thread to run an infinite task and communicate with a channel
+//! How to use an external thread to run an infinite task and communicate with a channel.
 
 use bevy::prelude::*;
 // Using crossbeam_channel instead of std as std `Receiver` is `!Sync`
diff --git a/examples/audio/audio.rs b/examples/audio/audio.rs
index d318c0bf4725f..82d5d01fadacb 100644
--- a/examples/audio/audio.rs
+++ b/examples/audio/audio.rs
@@ -1,4 +1,4 @@
-//! This example illustrates how to load and play an audio file
+//! This example illustrates how to load and play an audio file.
 
 use bevy::prelude::*;
 
diff --git a/examples/audio/audio_control.rs b/examples/audio/audio_control.rs
index 8db093c3f9bfc..13f3d9a1abb61 100644
--- a/examples/audio/audio_control.rs
+++ b/examples/audio/audio_control.rs
@@ -1,4 +1,4 @@
-//! This example illustrates how to load and play an audio file, and control how it's played
+//! This example illustrates how to load and play an audio file, and control how it's played.
 
 use bevy::{audio::AudioSink, prelude::*};
 
diff --git a/examples/diagnostics/custom_diagnostic.rs b/examples/diagnostics/custom_diagnostic.rs
index 62d85b147fac0..7e7dc1b095873 100644
--- a/examples/diagnostics/custom_diagnostic.rs
+++ b/examples/diagnostics/custom_diagnostic.rs
@@ -1,4 +1,4 @@
-//! This example illustrates how to create a custom diagnostic
+//! This example illustrates how to create a custom diagnostic.
 
 use bevy::{
     diagnostic::{Diagnostic, DiagnosticId, Diagnostics, LogDiagnosticsPlugin},
@@ -8,16 +8,16 @@ use bevy::{
 fn main() {
     App::new()
         .add_plugins(DefaultPlugins)
-        // The "print diagnostics" plugin is optional. It just visualizes our diagnostics in the
-        // console
+        // The "print diagnostics" plugin is optional.
+        // It just visualizes our diagnostics in the console.
         .add_plugin(LogDiagnosticsPlugin::default())
         .add_startup_system(setup_diagnostic_system)
         .add_system(my_system)
         .run();
 }
 
-// All diagnostics should have a unique DiagnosticId. for each new diagnostic, generate a new random
-// number
+// All diagnostics should have a unique DiagnosticId.
+// For each new diagnostic, generate a new random number.
 pub const SYSTEM_ITERATION_COUNT: DiagnosticId =
     DiagnosticId::from_u128(337040787172757619024841343456040760896);
 
@@ -32,6 +32,6 @@ fn setup_diagnostic_system(mut diagnostics: ResMut<Diagnostics>) {
 }
 
 fn my_system(mut diagnostics: ResMut<Diagnostics>) {
-    // Add a measurement of 10.0 for our diagnostic each time this system runs
+    // Add a measurement of 10.0 for our diagnostic each time this system runs.
     diagnostics.add_measurement(SYSTEM_ITERATION_COUNT, 10.0);
 }
diff --git a/examples/diagnostics/log_diagnostics.rs b/examples/diagnostics/log_diagnostics.rs
index 47ed62e99ae6a..5aff0b020958d 100644
--- a/examples/diagnostics/log_diagnostics.rs
+++ b/examples/diagnostics/log_diagnostics.rs
@@ -1,4 +1,4 @@
-//! Add a plugin that logs diagnostics, like frames per second (FPS), to the console
+//! Add a plugin that logs diagnostics, like frames per second (FPS), to the console.
 
 use bevy::{
     diagnostic::{FrameTimeDiagnosticsPlugin, LogDiagnosticsPlugin},
diff --git a/examples/ecs/component_change_detection.rs b/examples/ecs/component_change_detection.rs
index 87b947ca220c0..68e18a58469d8 100644
--- a/examples/ecs/component_change_detection.rs
+++ b/examples/ecs/component_change_detection.rs
@@ -1,4 +1,4 @@
-//! This example illustrates how to react to component change
+//! This example illustrates how to react to component change.
 
 use bevy::prelude::*;
 use rand::Rng;
diff --git a/examples/ecs/fixed_timestep.rs b/examples/ecs/fixed_timestep.rs
index 999563c258e0d..119783abdd63f 100644
--- a/examples/ecs/fixed_timestep.rs
+++ b/examples/ecs/fixed_timestep.rs
@@ -1,4 +1,4 @@
-//! Shows how to create systems that run every fixed timestep, rather than every tick
+//! Shows how to create systems that run every fixed timestep, rather than every tick.
 
 use bevy::{
     core::{FixedTimestep, FixedTimesteps},
diff --git a/examples/ecs/hierarchy.rs b/examples/ecs/hierarchy.rs
index 4dde980b62827..ad7bcbe2bb32d 100644
--- a/examples/ecs/hierarchy.rs
+++ b/examples/ecs/hierarchy.rs
@@ -1,4 +1,4 @@
-//! Creates a hierarchy of parents and children entities
+//! Creates a hierarchy of parents and children entities.
 
 use bevy::prelude::*;
 
diff --git a/examples/ecs/parallel_query.rs b/examples/ecs/parallel_query.rs
index 646cf0203baad..f10cb1df14839 100644
--- a/examples/ecs/parallel_query.rs
+++ b/examples/ecs/parallel_query.rs
@@ -1,4 +1,4 @@
-//! Illustrates parallel queries with `ParallelIterator`
+//! Illustrates parallel queries with `ParallelIterator`.
 
 use bevy::{prelude::*, tasks::prelude::*};
 use rand::random;
diff --git a/examples/ecs/startup_system.rs b/examples/ecs/startup_system.rs
index a56b1aa39bc24..f1a3e892cd3fa 100644
--- a/examples/ecs/startup_system.rs
+++ b/examples/ecs/startup_system.rs
@@ -1,4 +1,4 @@
-//! Demonstrates a startup system (one that runs once when the app starts up)
+//! Demonstrates a startup system (one that runs once when the app starts up).
 
 use bevy::prelude::*;
 
diff --git a/examples/ecs/system_chaining.rs b/examples/ecs/system_chaining.rs
index cb632d2089821..af8ae58d00f2d 100644
--- a/examples/ecs/system_chaining.rs
+++ b/examples/ecs/system_chaining.rs
@@ -1,4 +1,4 @@
-//! Illustrates how to use States to control transitioning from a Menu state to an `InGame` state
+//! Illustrates how to use States to control transitioning from a Menu state to an `InGame` state.
 
 use anyhow::Result;
 use bevy::prelude::*;
diff --git a/examples/ecs/system_param.rs b/examples/ecs/system_param.rs
index ddebd5fb17246..8539ad161f66d 100644
--- a/examples/ecs/system_param.rs
+++ b/examples/ecs/system_param.rs
@@ -1,4 +1,4 @@
-//! This example creates a [`SystemParam`] struct that counts the number of players
+//! This example creates a [`SystemParam`] struct that counts the number of players.
 
 use bevy::{ecs::system::SystemParam, prelude::*};
 
diff --git a/examples/ecs/timers.rs b/examples/ecs/timers.rs
index 433901259e61e..834bb6cf230a1 100644
--- a/examples/ecs/timers.rs
+++ b/examples/ecs/timers.rs
@@ -1,4 +1,4 @@
-//! Illustrates ticking `Timer` resources inside systems and handling their state
+//! Illustrates ticking `Timer` resources inside systems and handling their state.
 
 use bevy::{log::info, prelude::*};
 
diff --git a/examples/games/alien_cake_addict.rs b/examples/games/alien_cake_addict.rs
index 08f69f59cb538..9506f0cce1bab 100644
--- a/examples/games/alien_cake_addict.rs
+++ b/examples/games/alien_cake_addict.rs
@@ -1,4 +1,4 @@
-//! Eat the cakes. Eat them all. An example 3D game
+//! Eat the cakes. Eat them all. An example 3D game.
 
 use bevy::{core::FixedTimestep, ecs::schedule::SystemSet, prelude::*, render::camera::Camera3d};
 use rand::Rng;
diff --git a/examples/games/breakout.rs b/examples/games/breakout.rs
index 4c777fe325abd..6721f2c6537f5 100644
--- a/examples/games/breakout.rs
+++ b/examples/games/breakout.rs
@@ -1,4 +1,4 @@
-//! A simplified implementation of the classic game "Breakout"
+//! A simplified implementation of the classic game "Breakout".
 
 use bevy::{
     core::FixedTimestep,
diff --git a/examples/input/gamepad_input.rs b/examples/input/gamepad_input.rs
index c140a311f4655..9ad04ff2c8101 100644
--- a/examples/input/gamepad_input.rs
+++ b/examples/input/gamepad_input.rs
@@ -1,4 +1,4 @@
-//! Shows handling of gamepad input, connections, and disconnections
+//! Shows handling of gamepad input, connections, and disconnections.
 
 use bevy::{input::gamepad::GamepadButton, prelude::*};
 
diff --git a/examples/input/gamepad_input_events.rs b/examples/input/gamepad_input_events.rs
index 69cf09229dbc5..9bc020a22cde1 100644
--- a/examples/input/gamepad_input_events.rs
+++ b/examples/input/gamepad_input_events.rs
@@ -1,4 +1,4 @@
-//! Iterates and prints gamepad input and connection events
+//! Iterates and prints gamepad input and connection events.
 
 use bevy::{
     input::gamepad::{GamepadEvent, GamepadEventType},
diff --git a/examples/input/keyboard_input.rs b/examples/input/keyboard_input.rs
index 7df695f3cad9f..b235ae0c01136 100644
--- a/examples/input/keyboard_input.rs
+++ b/examples/input/keyboard_input.rs
@@ -1,4 +1,4 @@
-//! Demonstrates handling a key press/release
+//! Demonstrates handling a key press/release.
 
 use bevy::{
     input::{keyboard::KeyCode, Input},
diff --git a/examples/input/keyboard_input_events.rs b/examples/input/keyboard_input_events.rs
index 94e5e61519e1b..1353ed35878b5 100644
--- a/examples/input/keyboard_input_events.rs
+++ b/examples/input/keyboard_input_events.rs
@@ -1,4 +1,4 @@
-//! Prints out all keyboard events
+//! Prints out all keyboard events.
 
 use bevy::{input::keyboard::KeyboardInput, prelude::*};
 
diff --git a/examples/input/keyboard_modifiers.rs b/examples/input/keyboard_modifiers.rs
index 1691ea94754ec..0acb5672c4557 100644
--- a/examples/input/keyboard_modifiers.rs
+++ b/examples/input/keyboard_modifiers.rs
@@ -1,4 +1,4 @@
-//! Demonstrates using key modifiers (ctrl, shift)
+//! Demonstrates using key modifiers (ctrl, shift).
 
 use bevy::{
     input::{keyboard::KeyCode, Input},
diff --git a/examples/input/mouse_grab.rs b/examples/input/mouse_grab.rs
index a3654d9da80e7..be2014622d239 100644
--- a/examples/input/mouse_grab.rs
+++ b/examples/input/mouse_grab.rs
@@ -1,4 +1,4 @@
-//! Demonstrates handling a mouse button press/release
+//! Demonstrates handling a mouse button press/release.
 
 use bevy::prelude::*;
 
diff --git a/examples/input/mouse_input.rs b/examples/input/mouse_input.rs
index a0ec783d84a5d..06bdad45b6be5 100644
--- a/examples/input/mouse_input.rs
+++ b/examples/input/mouse_input.rs
@@ -1,4 +1,4 @@
-//! Prints out all mouse events (buttons, movement, etc.)
+//! Prints out all mouse events (buttons, movement, etc.).
 
 use bevy::prelude::*;
 
diff --git a/examples/input/mouse_input_events.rs b/examples/input/mouse_input_events.rs
index 0c12190b23aef..4fd328731d305 100644
--- a/examples/input/mouse_input_events.rs
+++ b/examples/input/mouse_input_events.rs
@@ -1,4 +1,4 @@
-//! Demonstrates how to grab the mouse, locking the cursor to the app's screen
+//! Demonstrates how to grab the mouse, locking the cursor to the app's screen.
 
 use bevy::{
     input::mouse::{MouseButtonInput, MouseMotion, MouseWheel},
diff --git a/examples/input/touch_input.rs b/examples/input/touch_input.rs
index 8a1e99bbd4ce3..b2427aebc4442 100644
--- a/examples/input/touch_input.rs
+++ b/examples/input/touch_input.rs
@@ -1,4 +1,4 @@
-//! Displays touch presses, releases, and cancels
+//! Displays touch presses, releases, and cancels.
 
 use bevy::{input::touch::*, prelude::*};
 
diff --git a/examples/input/touch_input_events.rs b/examples/input/touch_input_events.rs
index 7f940e6ee730d..665abd271e027 100644
--- a/examples/input/touch_input_events.rs
+++ b/examples/input/touch_input_events.rs
@@ -1,4 +1,4 @@
-//! Prints out all touch inputs
+//! Prints out all touch inputs.
 
 use bevy::{input::touch::*, prelude::*};
 
diff --git a/examples/reflection/generic_reflection.rs b/examples/reflection/generic_reflection.rs
index f6261e0c82751..3d09efec57421 100644
--- a/examples/reflection/generic_reflection.rs
+++ b/examples/reflection/generic_reflection.rs
@@ -1,4 +1,4 @@
-//! Demonstrates how reflection in Bevy provides a way to dynamically interact with Rust types
+//! Demonstrates how reflection in Bevy provides a way to dynamically interact with Rust types.
 
 use bevy::{prelude::*, reflect::TypeRegistry};
 use std::any::TypeId;
diff --git a/examples/reflection/reflection_types.rs b/examples/reflection/reflection_types.rs
index 255b671104ff0..cbbe6fe2add62 100644
--- a/examples/reflection/reflection_types.rs
+++ b/examples/reflection/reflection_types.rs
@@ -1,4 +1,4 @@
-//! This example illustrates the various reflection types available
+//! This example illustrates the various reflection types available.
 
 use bevy::{
     prelude::*,
diff --git a/examples/reflection/trait_reflection.rs b/examples/reflection/trait_reflection.rs
index 28cc81fc18467..0c4c4eaf4004c 100644
--- a/examples/reflection/trait_reflection.rs
+++ b/examples/reflection/trait_reflection.rs
@@ -1,4 +1,4 @@
-//! Allows reflection with trait objects
+//! Allows reflection with trait objects.
 
 use bevy::{prelude::*, reflect::TypeRegistry};
 
diff --git a/examples/scene/scene.rs b/examples/scene/scene.rs
index 0216be872b4c3..7518e1c32dc3d 100644
--- a/examples/scene/scene.rs
+++ b/examples/scene/scene.rs
@@ -1,4 +1,4 @@
-//! This example illustrates loading and saving scenes from files
+//! This example illustrates loading and saving scenes from files.
 
 use bevy::{prelude::*, reflect::TypeRegistry, utils::Duration};
 
diff --git a/examples/shader/compute_shader_game_of_life.rs b/examples/shader/compute_shader_game_of_life.rs
index 7049ce0212736..1b517a4e21c14 100644
--- a/examples/shader/compute_shader_game_of_life.rs
+++ b/examples/shader/compute_shader_game_of_life.rs
@@ -1,4 +1,4 @@
-//! A compute shader simulating Conway's Game of Life
+//! A compute shader simulating Conway's Game of Life.
 //! Compute shaders use the GPU for computing arbitrary information, that may be independent of what
 //! is rendered to the screen.
 
diff --git a/examples/shader/shader_defs.rs b/examples/shader/shader_defs.rs
index d6e8246e16075..c1275c6810c87 100644
--- a/examples/shader/shader_defs.rs
+++ b/examples/shader/shader_defs.rs
@@ -1,5 +1,5 @@
 //! Demonstrates creating a custom material that uses "shaders defs", a tool to selectively
-//! toggle parts of a shader
+//! toggle parts of a shader.
 
 use bevy::{
     core_pipeline::Transparent3d,
diff --git a/examples/shader/shader_material.rs b/examples/shader/shader_material.rs
index e56a21b5bca4c..2a0eebd88080c 100644
--- a/examples/shader/shader_material.rs
+++ b/examples/shader/shader_material.rs
@@ -1,4 +1,4 @@
-//! A custom shader sampling a texture with view-independent UV coordinates
+//! A custom shader sampling a texture with view-independent UV coordinates.
 
 use bevy::{
     ecs::system::{lifetimeless::SRes, SystemParamItem},
diff --git a/examples/shader/shader_material_screenspace_texture.rs b/examples/shader/shader_material_screenspace_texture.rs
index a23317da127b5..ebe30ee49b0cc 100644
--- a/examples/shader/shader_material_screenspace_texture.rs
+++ b/examples/shader/shader_material_screenspace_texture.rs
@@ -1,4 +1,4 @@
-//! A custom shader sampling a texture with view-independent UV coordinates
+//! A custom shader sampling a texture with view-independent UV coordinates.
 
 use bevy::{
     ecs::system::{lifetimeless::SRes, SystemParamItem},
diff --git a/examples/stress_tests/many_cubes.rs b/examples/stress_tests/many_cubes.rs
index e2d2befd94ed2..d8a92501fecbb 100644
--- a/examples/stress_tests/many_cubes.rs
+++ b/examples/stress_tests/many_cubes.rs
@@ -1,4 +1,4 @@
-//! Simple benchmark to test per-entity draw overhead
+//! Simple benchmark to test per-entity draw overhead.
 //!
 //! To measure performance realistically, be sure to run this in release mode.
 //! `cargo run --example many_cubes --release`
diff --git a/examples/transforms/3d_rotation.rs b/examples/transforms/3d_rotation.rs
index 12dbdc33c6fa9..2323c9c86a44b 100644
--- a/examples/transforms/3d_rotation.rs
+++ b/examples/transforms/3d_rotation.rs
@@ -1,4 +1,4 @@
-//! Illustrates how to (constantly) rotate an object around an axis
+//! Illustrates how to (constantly) rotate an object around an axis.
 
 use bevy::prelude::*;
 
diff --git a/examples/transforms/global_vs_local_translation.rs b/examples/transforms/global_vs_local_translation.rs
index 23d4a35272a3f..5998fc163d49b 100644
--- a/examples/transforms/global_vs_local_translation.rs
+++ b/examples/transforms/global_vs_local_translation.rs
@@ -1,5 +1,5 @@
 //! Illustrates the difference between direction of a translation in respect to local object or
-//! global object Transform
+//! global object Transform.
 
 use bevy::prelude::*;
 
diff --git a/examples/transforms/scale.rs b/examples/transforms/scale.rs
index d3770eecdf631..fd48fea98ce8a 100644
--- a/examples/transforms/scale.rs
+++ b/examples/transforms/scale.rs
@@ -1,4 +1,4 @@
-//! Illustrates how to scale an object in each direction
+//! Illustrates how to scale an object in each direction.
 
 use bevy::math::Vec3Swizzles;
 use bevy::prelude::*;
diff --git a/examples/transforms/transform.rs b/examples/transforms/transform.rs
index 39b5646fed150..c57856ff53ec0 100644
--- a/examples/transforms/transform.rs
+++ b/examples/transforms/transform.rs
@@ -1,4 +1,4 @@
-//! Shows multiple transformations of objects
+//! Shows multiple transformations of objects.
 
 use bevy::prelude::*;
 
diff --git a/examples/transforms/translation.rs b/examples/transforms/translation.rs
index 54901b2687d90..6a709a17abc39 100644
--- a/examples/transforms/translation.rs
+++ b/examples/transforms/translation.rs
@@ -1,4 +1,4 @@
-//! Illustrates how to move an object along an axis
+//! Illustrates how to move an object along an axis.
 
 use bevy::prelude::*;
 
diff --git a/examples/ui/text_debug.rs b/examples/ui/text_debug.rs
index 4389f4d228e72..0b65c7c722f64 100644
--- a/examples/ui/text_debug.rs
+++ b/examples/ui/text_debug.rs
@@ -1,4 +1,4 @@
-//! This example is for debugging text layout
+//! This example is for debugging text layout.
 
 use bevy::{
     diagnostic::{Diagnostics, FrameTimeDiagnosticsPlugin},
diff --git a/examples/window/clear_color.rs b/examples/window/clear_color.rs
index d8ba08cbb4175..60cf7b3e344db 100644
--- a/examples/window/clear_color.rs
+++ b/examples/window/clear_color.rs
@@ -1,4 +1,4 @@
-//! Creates a solid color window
+//! Creates a solid color window.
 
 use bevy::prelude::*;
 
diff --git a/examples/window/multiple_windows.rs b/examples/window/multiple_windows.rs
index 27844f7dd9bc6..2181d62a5b28b 100644
--- a/examples/window/multiple_windows.rs
+++ b/examples/window/multiple_windows.rs
@@ -1,4 +1,4 @@
-//! This example creates a second window and draws a mesh from two different cameras, one in each window
+//! This example creates a second window and draws a mesh from two different cameras, one in each window.
 
 use bevy::{
     core_pipeline::{self, AlphaMask3d, Opaque3d, Transparent3d},
diff --git a/examples/window/scale_factor_override.rs b/examples/window/scale_factor_override.rs
index 78a9072eae63f..67aefc9e13aa3 100644
--- a/examples/window/scale_factor_override.rs
+++ b/examples/window/scale_factor_override.rs
@@ -1,4 +1,4 @@
-//! This example illustrates how to customize the default window settings
+//! This example illustrates how to customize the default window settings.
 
 use bevy::prelude::*;
 
diff --git a/examples/window/transparent_window.rs b/examples/window/transparent_window.rs
index a5b11017eb318..4724d95bbdf79 100644
--- a/examples/window/transparent_window.rs
+++ b/examples/window/transparent_window.rs
@@ -1,4 +1,4 @@
-//! An example of how to display a window in transparent mode
+//! An example of how to display a window in transparent mode.
 //! [Documentation & Platform support.](https://docs.rs/bevy/latest/bevy/prelude/struct.WindowDescriptor.html#structfield.transparent)
 
 use bevy::{prelude::*, window::WindowDescriptor};
diff --git a/examples/window/window_settings.rs b/examples/window/window_settings.rs
index 7d45b68e6e2ba..5a48b7f047175 100644
--- a/examples/window/window_settings.rs
+++ b/examples/window/window_settings.rs
@@ -1,4 +1,4 @@
-//! This example illustrates how to customize the default window settings
+//! This example illustrates how to customize the default window settings.
 
 use bevy::{prelude::*, window::PresentMode};
 

From b2601377e1f78cdc98642a153399d06d13c012a2 Mon Sep 17 00:00:00 2001
From: Mark Schmale <masch@masch.it>
Date: Sun, 15 May 2022 09:59:12 +0200
Subject: [PATCH 22/23] applied @Nilirad's suggestions for example docs

---
 examples/3d/3d_scene.rs                        | 2 +-
 examples/3d/lighting.rs                        | 3 ++-
 examples/3d/parenting.rs                       | 2 +-
 examples/3d/render_to_texture.rs               | 2 +-
 examples/3d/spherical_area_lights.rs           | 2 +-
 examples/3d/update_gltf_scene.rs               | 2 +-
 examples/README.md                             | 4 ++--
 examples/app/headless_defaults.rs              | 2 +-
 examples/app/plugin.rs                         | 2 +-
 examples/app/plugin_group.rs                   | 4 ++--
 examples/app/return_after_run.rs               | 2 +-
 examples/asset/custom_asset.rs                 | 2 +-
 examples/asset/custom_asset_io.rs              | 4 ++--
 examples/asset/hot_asset_reloading.rs          | 6 +++---
 examples/diagnostics/log_diagnostics.rs        | 2 +-
 examples/ecs/custom_query_param.rs             | 2 +-
 examples/ecs/system_chaining.rs                | 3 ++-
 examples/ecs/system_param.rs                   | 2 +-
 examples/ecs/system_sets.rs                    | 4 ++--
 examples/ecs/timers.rs                         | 2 +-
 examples/input/mouse_grab.rs                   | 2 +-
 examples/input/mouse_input.rs                  | 2 +-
 examples/input/mouse_input_events.rs           | 2 +-
 examples/reflection/generic_reflection.rs      | 2 +-
 examples/reflection/reflection.rs              | 7 ++++---
 examples/reflection/reflection_types.rs        | 3 ++-
 examples/scene/scene.rs                        | 2 +-
 examples/shader/compute_shader_game_of_life.rs | 1 +
 examples/shader/shader_defs.rs                 | 4 ++--
 examples/shader/shader_material.rs             | 2 +-
 examples/stress_tests/many_cubes.rs            | 2 +-
 examples/tools/scene_viewer.rs                 | 3 ++-
 examples/ui/text.rs                            | 7 ++++---
 examples/ui/text_debug.rs                      | 2 +-
 examples/window/clear_color.rs                 | 4 +++-
 examples/window/low_power.rs                   | 1 +
 examples/window/multiple_windows.rs            | 2 +-
 examples/window/scale_factor_override.rs       | 3 ++-
 examples/window/transparent_window.rs          | 7 +++++--
 examples/window/window_settings.rs             | 3 ++-
 40 files changed, 65 insertions(+), 50 deletions(-)

diff --git a/examples/3d/3d_scene.rs b/examples/3d/3d_scene.rs
index b24993d9849ae..5cd7beff7c06d 100644
--- a/examples/3d/3d_scene.rs
+++ b/examples/3d/3d_scene.rs
@@ -1,4 +1,4 @@
-//! Simple 3D scene with basic shapes and lighting
+//! A simple 3D scene with light shining over a cube sitting on a plane.
 
 use bevy::prelude::*;
 
diff --git a/examples/3d/lighting.rs b/examples/3d/lighting.rs
index 3905ae8d47e15..592807c140f02 100644
--- a/examples/3d/lighting.rs
+++ b/examples/3d/lighting.rs
@@ -1,4 +1,5 @@
-//! Illustrates various lighting options in a simple scene.
+//! Illustrates different lights of various types and colors, some static, some moving over
+//! a simple scene.
 
 use bevy::prelude::*;
 
diff --git a/examples/3d/parenting.rs b/examples/3d/parenting.rs
index 5180b20c7a086..4e9f95f850722 100644
--- a/examples/3d/parenting.rs
+++ b/examples/3d/parenting.rs
@@ -1,4 +1,4 @@
-//! Illustrates how to create parent->child relationships between entities how parent transforms
+//! Illustrates how to create parent-child relationships between entities and how parent transforms
 //! are propagated to their descendants.
 
 use bevy::prelude::*;
diff --git a/examples/3d/render_to_texture.rs b/examples/3d/render_to_texture.rs
index 9d71e09ea24df..c8ca3b7a6d12b 100644
--- a/examples/3d/render_to_texture.rs
+++ b/examples/3d/render_to_texture.rs
@@ -1,4 +1,4 @@
-//! Shows how to render to a texture, useful for mirrors, UI, or exporting images.
+//! Shows how to render to a texture. Useful for mirrors, UI, or exporting images.
 
 use bevy::{
     core_pipeline::{
diff --git a/examples/3d/spherical_area_lights.rs b/examples/3d/spherical_area_lights.rs
index a5f84a4e4921e..094b66809fcfd 100644
--- a/examples/3d/spherical_area_lights.rs
+++ b/examples/3d/spherical_area_lights.rs
@@ -1,4 +1,4 @@
-//! Demonstrates how point light radius values affect light behavior.
+//! Demonstrates how lighting is affected by different radius of point lights.
 
 use bevy::prelude::*;
 
diff --git a/examples/3d/update_gltf_scene.rs b/examples/3d/update_gltf_scene.rs
index d876323648557..a72a29f76ae36 100644
--- a/examples/3d/update_gltf_scene.rs
+++ b/examples/3d/update_gltf_scene.rs
@@ -1,4 +1,4 @@
-//! Update a scene from a gltf file, either by spawning the scene as a child of another entity,
+//! Update a scene from a glTF file, either by spawning the scene as a child of another entity,
 //! or by accessing the entities of the scene.
 
 use bevy::{prelude::*, scene::InstanceId};
diff --git a/examples/README.md b/examples/README.md
index b27fa3dd55d93..a3d463d13cb76 100644
--- a/examples/README.md
+++ b/examples/README.md
@@ -248,7 +248,7 @@ Example | File | Description
 `shader_instancing` | [`shader/shader_instancing.rs`](./shader/shader_instancing.rs) | A custom shader showing off rendering a mesh multiple times in one draw call.
 `shader_material` | [`shader/shader_material.rs`](./shader/shader_material.rs) | Illustrates creating a custom material and a shader that uses it
 `shader_material_glsl` | [`shader/shader_material_glsl.rs`](./shader/shader_material_glsl.rs) | A custom shader using the GLSL shading language.
-`shader_material_screenspace_texture` | [`shader/shader_material_screenspace_texture.rs`](./shader/shader_material_screenspace_texture.rs) | A custom shader sampling a texture with view-independent UV coordinates
+`shader_material_screenspace_texture` | [`shader/shader_material_screenspace_texture.rs`](./shader/shader_material_screenspace_texture.rs) | A custom shader sampling a texture with view-independent UV coordinates.
 
 ## Stress Tests
 
@@ -286,7 +286,7 @@ Example | File | Description
 Example | File | Description
 --- | --- | ---
 `3d_rotation` | [`transforms/3d_rotation.rs`](./transforms/3d_rotation.rs) | Illustrates how to (constantly) rotate an object around an axis
-`global_vs_local_translation` | [`transforms/global_vs_local_translation.rs`](./transforms/global_vs_local_translation.rs) | Illustrates the difference between direction of a translation in respect to local object or global object Transform
+`global_vs_local_translation` | [`transforms/global_vs_local_translation.rs`](./transforms/global_vs_local_translation.rs) | Illustrates the difference between direction of a translation in respect to local object or global object Transform.
 `scale` | [`transforms/scale.rs`](./transforms/scale.rs) | Illustrates how to scale an object in each direction
 `transform` | [`transforms/transfrom.rs`](./transforms/transform.rs) | Shows multiple transformations of objects
 `translation` | [`transforms/translation.rs`](./transforms/translation.rs) | Illustrates how to move an object along an axis
diff --git a/examples/app/headless_defaults.rs b/examples/app/headless_defaults.rs
index 59dec5453ab63..72dbeba5ea383 100644
--- a/examples/app/headless_defaults.rs
+++ b/examples/app/headless_defaults.rs
@@ -1,4 +1,4 @@
-//! An application that runs with default plugins, but without an actual renderer
+//! An application that runs with default plugins, but without an actual renderer.
 //! This can be very useful for integration tests or CI.
 
 use bevy::{prelude::*, render::settings::WgpuSettings};
diff --git a/examples/app/plugin.rs b/examples/app/plugin.rs
index e757a62f645c7..e154ecd236a33 100644
--- a/examples/app/plugin.rs
+++ b/examples/app/plugin.rs
@@ -1,4 +1,4 @@
-//! Demonstrates the creation and registration of a custom plugin
+//! Demonstrates the creation and registration of a custom plugin.
 //!
 //! Plugins are the foundation of Bevy. They are scoped sets of components, resources, and systems
 //! that provide a specific piece of functionality (generally the smaller the scope, the better).
diff --git a/examples/app/plugin_group.rs b/examples/app/plugin_group.rs
index d898c20f350db..5eb4a27a7cd02 100644
--- a/examples/app/plugin_group.rs
+++ b/examples/app/plugin_group.rs
@@ -1,5 +1,5 @@
-//! Demonstrates the creation and registration of a custom plugin group
-//! [`PluginGroups`] are a way to group sets of plugins that should be registered together.
+//! Demonstrates the creation and registration of a custom plugin group.
+//! [`PluginGroup`]s are a way to group sets of plugins that should be registered together.
 
 use bevy::{app::PluginGroupBuilder, prelude::*};
 
diff --git a/examples/app/return_after_run.rs b/examples/app/return_after_run.rs
index 813a563143a6b..d1ef945390083 100644
--- a/examples/app/return_after_run.rs
+++ b/examples/app/return_after_run.rs
@@ -1,4 +1,4 @@
-//! Show how to return to main after the Bevy app has exited.
+//! Shows how to return to the calling function after a windowed Bevy app has exited.
 
 use bevy::{prelude::*, winit::WinitSettings};
 
diff --git a/examples/asset/custom_asset.rs b/examples/asset/custom_asset.rs
index 34698b57899ec..3462f3e511e64 100644
--- a/examples/asset/custom_asset.rs
+++ b/examples/asset/custom_asset.rs
@@ -1,4 +1,4 @@
-//! Implements a custom asset loader.
+//! Implements loader for a custom asset type.
 
 use bevy::{
     asset::{AssetLoader, LoadContext, LoadedAsset},
diff --git a/examples/asset/custom_asset_io.rs b/examples/asset/custom_asset_io.rs
index 2763a01a19e10..2475e5b46f0ca 100644
--- a/examples/asset/custom_asset_io.rs
+++ b/examples/asset/custom_asset_io.rs
@@ -1,6 +1,6 @@
 //! Implements a custom asset io loader.
-//! An [`AssetIo`] load is what the assert server uses to read the raw bytes of assets.
-//! It does not know anything about the asset formats, only how to talk the underlying storage.
+//! An [`AssetIo`] is what the asset server uses to read the raw bytes of assets.
+//! It does not know anything about the asset formats, only how to talk to the underlying storage.
 
 use bevy::{
     asset::{AssetIo, AssetIoError, Metadata},
diff --git a/examples/asset/hot_asset_reloading.rs b/examples/asset/hot_asset_reloading.rs
index d219dbb110abc..4bb6b744e7914 100644
--- a/examples/asset/hot_asset_reloading.rs
+++ b/examples/asset/hot_asset_reloading.rs
@@ -1,6 +1,6 @@
-//! Hot reloading allows you to modify assets on disk and they will be "live reloaded" while your
-//! game is running. This lets you immediately see the results of your changes without restarting
-//! the game. This example illustrates hot reloading mesh changes.
+//! Hot reloading allows you to modify assets files to be immediately reloaded while your game is
+//! running. This lets you immediately see the results of your changes without restarting the game.
+//! This example illustrates hot reloading mesh changes.
 
 use bevy::{asset::AssetServerSettings, prelude::*};
 
diff --git a/examples/diagnostics/log_diagnostics.rs b/examples/diagnostics/log_diagnostics.rs
index 5aff0b020958d..3af2af71df870 100644
--- a/examples/diagnostics/log_diagnostics.rs
+++ b/examples/diagnostics/log_diagnostics.rs
@@ -1,4 +1,4 @@
-//! Add a plugin that logs diagnostics, like frames per second (FPS), to the console.
+//! Shows different built-in plugins that logs diagnostics, like frames per second (FPS), to the console.
 
 use bevy::{
     diagnostic::{FrameTimeDiagnosticsPlugin, LogDiagnosticsPlugin},
diff --git a/examples/ecs/custom_query_param.rs b/examples/ecs/custom_query_param.rs
index 7804ad84ddff9..4dd4f266d63ab 100644
--- a/examples/ecs/custom_query_param.rs
+++ b/examples/ecs/custom_query_param.rs
@@ -1,4 +1,4 @@
-//! This examples illustrates the usage of the `WorldQuery` derive macro, which allows
+//! This example illustrates the usage of the `WorldQuery` derive macro, which allows
 //! defining custom query and filter types.
 //!
 //! While regular tuple queries work great in most of simple scenarios, using custom queries
diff --git a/examples/ecs/system_chaining.rs b/examples/ecs/system_chaining.rs
index af8ae58d00f2d..65b0401aa24e0 100644
--- a/examples/ecs/system_chaining.rs
+++ b/examples/ecs/system_chaining.rs
@@ -1,4 +1,5 @@
-//! Illustrates how to use States to control transitioning from a Menu state to an `InGame` state.
+//! Illustrates how to make a single system from multiple functions running in sequence and sharing
+//! their inputs and outputs.
 
 use anyhow::Result;
 use bevy::prelude::*;
diff --git a/examples/ecs/system_param.rs b/examples/ecs/system_param.rs
index 8539ad161f66d..176caa716d629 100644
--- a/examples/ecs/system_param.rs
+++ b/examples/ecs/system_param.rs
@@ -1,4 +1,4 @@
-//! This example creates a [`SystemParam`] struct that counts the number of players.
+//! This example creates a custom [`SystemParam`] struct that counts the number of players.
 
 use bevy::{ecs::system::SystemParam, prelude::*};
 
diff --git a/examples/ecs/system_sets.rs b/examples/ecs/system_sets.rs
index fe9e4c9b62313..e463c591e331e 100644
--- a/examples/ecs/system_sets.rs
+++ b/examples/ecs/system_sets.rs
@@ -1,4 +1,4 @@
-//! This example realizes the following scheme:
+//! Shows how systems with a similar purpose can be grouped into sets.
 //!
 //! ```none
 //! Physics                     (Criteria: App has run < 1.0 seconds)
@@ -19,7 +19,7 @@
 //! The two systems here (collision, sfx) are not specified to run in any order, and the actual
 //! ordering can then change between invocations.
 //!
-//! Lastly a system with run criterion _done_ is used to exit the app.
+//! Lastly a system with run criteria  _done_ is used to exit the app.
 
 use bevy::{app::AppExit, ecs::schedule::ShouldRun, prelude::*};
 
diff --git a/examples/ecs/timers.rs b/examples/ecs/timers.rs
index 834bb6cf230a1..758c00bca292b 100644
--- a/examples/ecs/timers.rs
+++ b/examples/ecs/timers.rs
@@ -1,4 +1,4 @@
-//! Illustrates ticking `Timer` resources inside systems and handling their state.
+//! Illustrates how `Timer`s can be used both as resources and components.
 
 use bevy::{log::info, prelude::*};
 
diff --git a/examples/input/mouse_grab.rs b/examples/input/mouse_grab.rs
index be2014622d239..7662814e27579 100644
--- a/examples/input/mouse_grab.rs
+++ b/examples/input/mouse_grab.rs
@@ -1,4 +1,4 @@
-//! Demonstrates handling a mouse button press/release.
+//! Demonstrates how to grab and hide the mouse cursor.
 
 use bevy::prelude::*;
 
diff --git a/examples/input/mouse_input.rs b/examples/input/mouse_input.rs
index 06bdad45b6be5..918a6713c2a75 100644
--- a/examples/input/mouse_input.rs
+++ b/examples/input/mouse_input.rs
@@ -1,4 +1,4 @@
-//! Prints out all mouse events (buttons, movement, etc.).
+//! Prints mouse button events.
 
 use bevy::prelude::*;
 
diff --git a/examples/input/mouse_input_events.rs b/examples/input/mouse_input_events.rs
index 4fd328731d305..547038f40cb32 100644
--- a/examples/input/mouse_input_events.rs
+++ b/examples/input/mouse_input_events.rs
@@ -1,4 +1,4 @@
-//! Demonstrates how to grab the mouse, locking the cursor to the app's screen.
+//! Prints all mouse events to the console.
 
 use bevy::{
     input::mouse::{MouseButtonInput, MouseMotion, MouseWheel},
diff --git a/examples/reflection/generic_reflection.rs b/examples/reflection/generic_reflection.rs
index 3d09efec57421..072bed411611a 100644
--- a/examples/reflection/generic_reflection.rs
+++ b/examples/reflection/generic_reflection.rs
@@ -1,4 +1,4 @@
-//! Demonstrates how reflection in Bevy provides a way to dynamically interact with Rust types.
+//! Demonstrates how reflection is used with generic Rust types.
 
 use bevy::{prelude::*, reflect::TypeRegistry};
 use std::any::TypeId;
diff --git a/examples/reflection/reflection.rs b/examples/reflection/reflection.rs
index 5c90f1d1f3969..8197299cb1732 100644
--- a/examples/reflection/reflection.rs
+++ b/examples/reflection/reflection.rs
@@ -1,7 +1,8 @@
-//! This example illustrates how "reflection" works in Bevy.
-//! Reflection provide a way to dynamically interact with Rust types, such as accessing fields
+//! Illustrates how "reflection" works in Bevy.
+//!
+//! Reflection provides a way to dynamically interact with Rust types, such as accessing fields
 //! by their string name. Reflection is a core part of Bevy and enables a number of interesting
-//! scenarios (like scenes).
+//! features (like scenes).
 
 use bevy::{
     prelude::*,
diff --git a/examples/reflection/reflection_types.rs b/examples/reflection/reflection_types.rs
index cbbe6fe2add62..c621cc786ca44 100644
--- a/examples/reflection/reflection_types.rs
+++ b/examples/reflection/reflection_types.rs
@@ -1,4 +1,5 @@
-//! This example illustrates the various reflection types available.
+//! This example illustrates how reflection works for simple data structures, like
+//! structs, tuples and vectors.
 
 use bevy::{
     prelude::*,
diff --git a/examples/scene/scene.rs b/examples/scene/scene.rs
index 7518e1c32dc3d..51d6f55aefac5 100644
--- a/examples/scene/scene.rs
+++ b/examples/scene/scene.rs
@@ -1,4 +1,4 @@
-//! This example illustrates loading and saving scenes from files.
+//! This example illustrates loading scenes from files.
 
 use bevy::{prelude::*, reflect::TypeRegistry, utils::Duration};
 
diff --git a/examples/shader/compute_shader_game_of_life.rs b/examples/shader/compute_shader_game_of_life.rs
index 1b517a4e21c14..37a8c609b6f3b 100644
--- a/examples/shader/compute_shader_game_of_life.rs
+++ b/examples/shader/compute_shader_game_of_life.rs
@@ -1,4 +1,5 @@
 //! A compute shader simulating Conway's Game of Life.
+//!
 //! Compute shaders use the GPU for computing arbitrary information, that may be independent of what
 //! is rendered to the screen.
 
diff --git a/examples/shader/shader_defs.rs b/examples/shader/shader_defs.rs
index c1275c6810c87..e355ab6fafd11 100644
--- a/examples/shader/shader_defs.rs
+++ b/examples/shader/shader_defs.rs
@@ -1,5 +1,5 @@
-//! Demonstrates creating a custom material that uses "shaders defs", a tool to selectively
-//! toggle parts of a shader.
+//! Demonstrates creating a custom material that uses "shaders defs", a tool that enables
+//! conditional compilation in shaders.
 
 use bevy::{
     core_pipeline::Transparent3d,
diff --git a/examples/shader/shader_material.rs b/examples/shader/shader_material.rs
index 2a0eebd88080c..d0eae8481f814 100644
--- a/examples/shader/shader_material.rs
+++ b/examples/shader/shader_material.rs
@@ -1,4 +1,4 @@
-//! A custom shader sampling a texture with view-independent UV coordinates.
+//! Illustrates creating a custom material and a shader that uses it.
 
 use bevy::{
     ecs::system::{lifetimeless::SRes, SystemParamItem},
diff --git a/examples/stress_tests/many_cubes.rs b/examples/stress_tests/many_cubes.rs
index d8a92501fecbb..9c996e9a40a59 100644
--- a/examples/stress_tests/many_cubes.rs
+++ b/examples/stress_tests/many_cubes.rs
@@ -3,7 +3,7 @@
 //! To measure performance realistically, be sure to run this in release mode.
 //! `cargo run --example many_cubes --release`
 //!
-//! Per default this arranges the meshes in a cubical pattern, where the number of visible meshes
+//! By default, this arranges the meshes in a cubical pattern, where the number of visible meshes
 //! varies with the viewing angle. You can choose to run the demo with a spherical pattern that
 //! distributes the meshes evenly.
 //!
diff --git a/examples/tools/scene_viewer.rs b/examples/tools/scene_viewer.rs
index fb900ada01e28..1dbcc115fd62c 100644
--- a/examples/tools/scene_viewer.rs
+++ b/examples/tools/scene_viewer.rs
@@ -1,4 +1,5 @@
-//! A simple way to view glTF models with Bevy.
+//! A simple glTF scene viewer made with Bevy.
+//!
 //! Just run `cargo run --release --example scene_viewer /path/to/model.gltf#Scene0`,
 //! replacing the path as appropriate.
 //! With no arguments it will load the `FieldHelmet` glTF model from the repository assets subdirectory.
diff --git a/examples/ui/text.rs b/examples/ui/text.rs
index 173ac80b47a03..70490ffeceb2a 100644
--- a/examples/ui/text.rs
+++ b/examples/ui/text.rs
@@ -1,6 +1,7 @@
-//! This example illustrates how to create UI text and update it in a system. It displays the
-//! current FPS in the top left corner, as well as text that changes colour in the bottom right.
-//! For text within a scene, please see the text2d example.
+//! This example illustrates how to create UI text and update it in a system.
+//!
+//! It displays the current FPS in the top left corner, as well as text that changes color
+//! in the bottom right. For text within a scene, please see the text2d example.
 
 use bevy::{
     diagnostic::{Diagnostics, FrameTimeDiagnosticsPlugin},
diff --git a/examples/ui/text_debug.rs b/examples/ui/text_debug.rs
index 0b65c7c722f64..1c3c63503bd13 100644
--- a/examples/ui/text_debug.rs
+++ b/examples/ui/text_debug.rs
@@ -1,4 +1,4 @@
-//! This example is for debugging text layout.
+//! Shows various text layout options.
 
 use bevy::{
     diagnostic::{Diagnostics, FrameTimeDiagnosticsPlugin},
diff --git a/examples/window/clear_color.rs b/examples/window/clear_color.rs
index 60cf7b3e344db..62db50cda691d 100644
--- a/examples/window/clear_color.rs
+++ b/examples/window/clear_color.rs
@@ -1,4 +1,6 @@
-//! Creates a solid color window.
+//! Shows how to set the solid color that is used to paint the window before the frame gets drawn.
+//!
+//! Acts as background color, since pixels that are not drawn in a frame remain unchanged.
 
 use bevy::prelude::*;
 
diff --git a/examples/window/low_power.rs b/examples/window/low_power.rs
index 52a7bc240202f..e84a5be73dce2 100644
--- a/examples/window/low_power.rs
+++ b/examples/window/low_power.rs
@@ -1,4 +1,5 @@
 //! This example illustrates how to run a winit window in a reactive, low power mode.
+//!
 //! This is useful for making desktop applications, or any other program that doesn't need to be
 //! running the event loop non-stop.
 
diff --git a/examples/window/multiple_windows.rs b/examples/window/multiple_windows.rs
index 2181d62a5b28b..3d2125febc834 100644
--- a/examples/window/multiple_windows.rs
+++ b/examples/window/multiple_windows.rs
@@ -1,4 +1,4 @@
-//! This example creates a second window and draws a mesh from two different cameras, one in each window.
+//! Uses two windows to visualize a 3D model from different angles.
 
 use bevy::{
     core_pipeline::{self, AlphaMask3d, Opaque3d, Transparent3d},
diff --git a/examples/window/scale_factor_override.rs b/examples/window/scale_factor_override.rs
index 67aefc9e13aa3..cb428d80e1f64 100644
--- a/examples/window/scale_factor_override.rs
+++ b/examples/window/scale_factor_override.rs
@@ -1,4 +1,5 @@
-//! This example illustrates how to customize the default window settings.
+//! This example illustrates how to override the window scale factor imposed by the
+//! operating system.
 
 use bevy::prelude::*;
 
diff --git a/examples/window/transparent_window.rs b/examples/window/transparent_window.rs
index 4724d95bbdf79..3be9efa8c5d0d 100644
--- a/examples/window/transparent_window.rs
+++ b/examples/window/transparent_window.rs
@@ -1,5 +1,8 @@
-//! An example of how to display a window in transparent mode.
-//! [Documentation & Platform support.](https://docs.rs/bevy/latest/bevy/prelude/struct.WindowDescriptor.html#structfield.transparent)
+//! Shows how to display a window in transparent mode.
+//!
+//! This feature works as expected depending on the platform. Please check the
+//! [documentation](https://docs.rs/bevy/latest/bevy/prelude/struct.WindowDescriptor.html#structfield.transparent)
+//! for more details.
 
 use bevy::{prelude::*, window::WindowDescriptor};
 
diff --git a/examples/window/window_settings.rs b/examples/window/window_settings.rs
index 5a48b7f047175..ef11098faa904 100644
--- a/examples/window/window_settings.rs
+++ b/examples/window/window_settings.rs
@@ -1,4 +1,5 @@
-//! This example illustrates how to customize the default window settings.
+//! Illustrates how to change window settings and shows how to affect
+//! the mouse pointer in various ways.
 
 use bevy::{prelude::*, window::PresentMode};
 

From cbc2470f38aca7024366e1afcadf5326aff54ff1 Mon Sep 17 00:00:00 2001
From: Mark Schmale <masch@masch.it>
Date: Sun, 15 May 2022 10:11:00 +0200
Subject: [PATCH 23/23] added basic docs for the new example that had none.

---
 examples/2d/shapes.rs          | 2 ++
 examples/3d/vertex_colors.rs   | 2 ++
 examples/ecs/system_closure.rs | 2 ++
 3 files changed, 6 insertions(+)

diff --git a/examples/2d/shapes.rs b/examples/2d/shapes.rs
index 5fe8653ca68a6..8585c42121e34 100644
--- a/examples/2d/shapes.rs
+++ b/examples/2d/shapes.rs
@@ -1,3 +1,5 @@
+//! Shows how to render simple primitive shapes with a single color.
+
 use bevy::{prelude::*, sprite::MaterialMesh2dBundle};
 
 fn main() {
diff --git a/examples/3d/vertex_colors.rs b/examples/3d/vertex_colors.rs
index 4050230ae765a..a16f030f955c7 100644
--- a/examples/3d/vertex_colors.rs
+++ b/examples/3d/vertex_colors.rs
@@ -1,3 +1,5 @@
+//! Illustrates the use of vertex colors.
+
 use bevy::{prelude::*, render::mesh::VertexAttributeValues};
 
 fn main() {
diff --git a/examples/ecs/system_closure.rs b/examples/ecs/system_closure.rs
index 3ff06f82327d4..51612ba35cf35 100644
--- a/examples/ecs/system_closure.rs
+++ b/examples/ecs/system_closure.rs
@@ -1,3 +1,5 @@
+//! Shows how anonymous functions / closures can be used as systems.
+
 use bevy::{log::LogPlugin, prelude::*};
 
 fn main() {