From 1ba742937139c049ce5aafc8bc1bb3b9c8f0c201 Mon Sep 17 00:00:00 2001
From: Mark Schmale <masch@masch.it>
Date: Mon, 16 May 2022 13:53:20 +0000
Subject: [PATCH] Doc/module style doc blocks for examples (#4438)

# Objective

Provide a starting point for #3951, or a partial solution.
Providing a few comment blocks to discuss, and hopefully find better one in the process.

## Solution

Since I am pretty new to pretty much anything in this context, I figured I'd just start with a draft for some file level doc blocks. For some of them I found more relevant details (or at least things I considered interessting), for some others there is less.

## Changelog

- Moved some existing comments from main() functions in the 2d examples to the file header level
- Wrote some more comment blocks for most other 2d examples

TODO:
- [x] 2d/sprite_sheet, wasnt able to come up with something good yet
- [x] all other example groups...


Also: Please let me know if the commit style is okay, or to verbose. I could certainly squash these things, or add more details if needed.
I also hope its okay to raise this PR this early, with just a few files changed. Took me long enough and I dont wanted to let it go to waste because I lost motivation to do the whole thing. Additionally I am somewhat uncertain over the style and contents of the commets. So let me know what you thing please.
---
 examples/2d/mesh2d.rs                         |  2 +
 examples/2d/mesh2d_manual.rs                  |  8 +--
 examples/2d/move_sprite.rs                    |  4 ++
 examples/2d/rotation.rs                       |  2 +
 examples/2d/shapes.rs                         |  2 +
 examples/2d/sprite.rs                         |  2 +
 examples/2d/sprite_flipping.rs                |  2 +
 examples/2d/sprite_sheet.rs                   |  3 ++
 examples/2d/text2d.rs                         |  7 +++
 examples/2d/texture_atlas.rs                  |  5 +-
 examples/3d/3d_scene.rs                       |  2 +
 examples/3d/lighting.rs                       |  3 ++
 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/two_passes.rs                     |  4 ++
 examples/3d/update_gltf_scene.rs              |  3 ++
 examples/3d/vertex_colors.rs                  |  2 +
 examples/3d/wireframe.rs                      |  2 +
 examples/README.md                            | 14 ++---
 examples/animation/animated_fox.rs            |  2 +
 examples/animation/animated_transform.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             |  3 ++
 examples/app/logs.rs                          |  3 +-
 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             |  4 ++
 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     | 13 ++---
 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               |  3 ++
 examples/ecs/system_closure.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           |  6 ++-
 examples/games/breakout.rs                    |  2 +-
 examples/games/contributors.rs                |  2 +
 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             |  9 ++--
 examples/reflection/reflection_types.rs       |  4 +-
 examples/reflection/trait_reflection.rs       |  2 +
 examples/scene/scene.rs                       |  3 +-
 examples/shader/animate_shader.rs             |  4 ++
 .../shader/compute_shader_game_of_life.rs     |  6 +++
 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/stress_tests/many_lights.rs          |  3 ++
 examples/stress_tests/many_sprites.rs         |  9 +++-
 examples/stress_tests/transform_hierarchy.rs  |  2 +-
 examples/tools/scene_viewer.rs                |  7 +++
 examples/transforms/3d_rotation.rs            |  2 +
 .../transforms/global_vs_local_translation.rs |  8 ++-
 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                           |  8 +--
 examples/ui/text_debug.rs                     |  3 +-
 examples/ui/ui.rs                             |  3 +-
 examples/window/clear_color.rs                |  4 ++
 examples/window/low_power.rs                  |  8 +--
 examples/window/multiple_windows.rs           |  3 +-
 examples/window/scale_factor_override.rs      |  4 +-
 examples/window/transparent_window.rs         |  8 ++-
 examples/window/window_settings.rs            |  4 +-
 120 files changed, 425 insertions(+), 177 deletions(-)

diff --git a/examples/2d/mesh2d.rs b/examples/2d/mesh2d.rs
index 8b968a3966..6412c97f88 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() {
diff --git a/examples/2d/mesh2d_manual.rs b/examples/2d/mesh2d_manual.rs
index e585018aa5..0fea936b4f 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)
diff --git a/examples/2d/move_sprite.rs b/examples/2d/move_sprite.rs
index a895212b3a..856adcd31b 100644
--- a/examples/2d/move_sprite.rs
+++ b/examples/2d/move_sprite.rs
@@ -1,3 +1,5 @@
+//! Renders a 2D scene containing a single, moving sprite.
+
 use bevy::prelude::*;
 
 fn main() {
@@ -25,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 1eeab613cb..73313ea53a 100644
--- a/examples/2d/rotation.rs
+++ b/examples/2d/rotation.rs
@@ -1,3 +1,5 @@
+//! Demonstrates rotating entities in 2D using quaternions.
+
 use bevy::{
     core::FixedTimestep,
     math::{const_vec2, Vec3Swizzles},
diff --git a/examples/2d/shapes.rs b/examples/2d/shapes.rs
index 5fe8653ca6..8585c42121 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/2d/sprite.rs b/examples/2d/sprite.rs
index 6620aa9619..6ebe25dc19 100644
--- a/examples/2d/sprite.rs
+++ b/examples/2d/sprite.rs
@@ -1,3 +1,5 @@
+//! Displays a single [`Sprite`], created from an image.
+
 use bevy::prelude::*;
 
 fn main() {
diff --git a/examples/2d/sprite_flipping.rs b/examples/2d/sprite_flipping.rs
index e89968cf96..7617415720 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() {
diff --git a/examples/2d/sprite_sheet.rs b/examples/2d/sprite_sheet.rs
index d3d313fab2..59970231f3 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 e346cee724..bb7c908769 100644
--- a/examples/2d/text2d.rs
+++ b/examples/2d/text2d.rs
@@ -1,3 +1,10 @@
+//! 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.
+//!
+//! 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() {
diff --git a/examples/2d/texture_atlas.rs b/examples/2d/texture_atlas.rs
index 8aa7bcae43..45f7a24606 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>()
diff --git a/examples/3d/3d_scene.rs b/examples/3d/3d_scene.rs
index 6f2a311714..5cd7beff7c 100644
--- a/examples/3d/3d_scene.rs
+++ b/examples/3d/3d_scene.rs
@@ -1,3 +1,5 @@
+//! A simple 3D scene with light shining over a cube sitting on a plane.
+
 use bevy::prelude::*;
 
 fn main() {
diff --git a/examples/3d/lighting.rs b/examples/3d/lighting.rs
index 7feb35250c..592807c140 100644
--- a/examples/3d/lighting.rs
+++ b/examples/3d/lighting.rs
@@ -1,3 +1,6 @@
+//! Illustrates different lights of various types and colors, some static, some moving over
+//! a simple scene.
+
 use bevy::prelude::*;
 
 fn main() {
diff --git a/examples/3d/load_gltf.rs b/examples/3d/load_gltf.rs
index c309852251..c8a6047d99 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 8719658577..d7f8534da3 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 5eeddcfda1..5cdd163829 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 8601e98f61..4e9f95f850 100644
--- a/examples/3d/parenting.rs
+++ b/examples/3d/parenting.rs
@@ -1,7 +1,8 @@
+//! Illustrates how to create parent-child relationships between entities and 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 0565e18693..7a5a6bd7b4 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 fb27722342..c8ca3b7a6d 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 12516debe5..2f5e7adb30 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 fb93f62ab3..c58994ce5b 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 8347789e69..094b66809f 100644
--- a/examples/3d/spherical_area_lights.rs
+++ b/examples/3d/spherical_area_lights.rs
@@ -1,3 +1,5 @@
+//! Demonstrates how lighting is affected by different radius of point lights.
+
 use bevy::prelude::*;
 
 fn main() {
diff --git a/examples/3d/texture.rs b/examples/3d/texture.rs
index 7ee3384add..9a0e44d93f 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/two_passes.rs b/examples/3d/two_passes.rs
index ecf161506f..e9c5a64f23 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/3d/update_gltf_scene.rs b/examples/3d/update_gltf_scene.rs
index 3a23e82028..a72a29f76a 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/vertex_colors.rs b/examples/3d/vertex_colors.rs
index 4050230ae7..a16f030f95 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/3d/wireframe.rs b/examples/3d/wireframe.rs
index 96be8a9cbe..df36a1218d 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/README.md b/examples/README.md
index 7e69d51858..a3d463d13c 100644
--- a/examples/README.md
+++ b/examples/README.md
@@ -241,14 +241,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
 
@@ -279,14 +279,14 @@ 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
 
 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
diff --git a/examples/animation/animated_fox.rs b/examples/animation/animated_fox.rs
index 772208dd26..3432e859aa 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/animated_transform.rs b/examples/animation/animated_transform.rs
index 5084253615..fb9454ae41 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::*;
diff --git a/examples/animation/custom_skinned_mesh.rs b/examples/animation/custom_skinned_mesh.rs
index 5216cd08a6..404368db7d 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 ba318e2256..7cb8f90d11 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 d845617f0c..f9f1e607e2 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 3615aab7eb..6dc64d50d3 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 032a096968..758ff94555 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 5aaacce1fc..445ed9fa3a 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 4dbbcda903..2b3451647e 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 c299125677..72dbeba5ea 100644
--- a/examples/app/headless_defaults.rs
+++ b/examples/app/headless_defaults.rs
@@ -1,3 +1,6 @@
+//! 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};
 
 fn main() {
diff --git a/examples/app/logs.rs b/examples/app/logs.rs
index cdc6b5db01..029637b608 100644
--- a/examples/app/logs.rs
+++ b/examples/app/logs.rs
@@ -1,6 +1,7 @@
+//! 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 93600d943f..e154ecd236 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 0300f8a01f..5eb4a27a7c 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.
+//! [`PluginGroup`]s 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 7d4968c83e..d1ef945390 100644
--- a/examples/app/return_after_run.rs
+++ b/examples/app/return_after_run.rs
@@ -1,3 +1,5 @@
+//! Shows how to return to the calling function after a windowed 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 b53273b584..e49ab1636c 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 50aaa3880a..1339509725 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 4ca42e3503..e5693f4ddc 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 820d62394e..3462f3e511 100644
--- a/examples/asset/custom_asset.rs
+++ b/examples/asset/custom_asset.rs
@@ -1,3 +1,5 @@
+//! Implements loader for a custom asset type.
+
 use bevy::{
     asset::{AssetLoader, LoadContext, LoadedAsset},
     prelude::*,
diff --git a/examples/asset/custom_asset_io.rs b/examples/asset/custom_asset_io.rs
index af74a93d2b..2475e5b46f 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`] 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},
     prelude::*,
diff --git a/examples/asset/hot_asset_reloading.rs b/examples/asset/hot_asset_reloading.rs
index 0081330590..4bb6b744e7 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 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::*};
 
-/// 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 9182ac4879..6a4039e5a3 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 6b2cec163c..2cb0c04b50 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 2ff6f92ba1..82d5d01fad 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 ea218b9248..13f3d9a1ab 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 7f289d9f5b..7e7dc1b095 100644
--- a/examples/diagnostics/custom_diagnostic.rs
+++ b/examples/diagnostics/custom_diagnostic.rs
@@ -1,22 +1,23 @@
+//! 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)
-        // 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);
 
@@ -31,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 8c1447e60b..3af2af71df 100644
--- a/examples/diagnostics/log_diagnostics.rs
+++ b/examples/diagnostics/log_diagnostics.rs
@@ -1,3 +1,5 @@
+//! Shows different built-in plugins 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 01473c7749..68e18a5846 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 b18275794d..4dd4f266d6 100644
--- a/examples/ecs/custom_query_param.rs
+++ b/examples/ecs/custom_query_param.rs
@@ -1,22 +1,23 @@
+//! 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
+//! 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 c199a0019d..b27ed06f57 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 bb04b14004..f4c93c44d4 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 f89d304668..119783abdd 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 2e3a130999..0d3f3c3177 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 c67dfac85e..ad7bcbe2bb 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 e4122f17f7..73ab158408 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 a70eecf6d8..f10cb1df14 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 876ff4f916..c8bd75e063 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 82437b03af..f1a3e892cd 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 2371783ea1..82a07f2f22 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 026fc0f220..65b0401aa2 100644
--- a/examples/ecs/system_chaining.rs
+++ b/examples/ecs/system_chaining.rs
@@ -1,3 +1,6 @@
+//! 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_closure.rs b/examples/ecs/system_closure.rs
index 3ff06f8232..51612ba35c 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() {
diff --git a/examples/ecs/system_param.rs b/examples/ecs/system_param.rs
index fdb9e5038d..176caa716d 100644
--- a/examples/ecs/system_param.rs
+++ b/examples/ecs/system_param.rs
@@ -1,6 +1,7 @@
+//! This example creates a custom [`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 642f9f49d2..e463c591e3 100644
--- a/examples/ecs/system_sets.rs
+++ b/examples/ecs/system_sets.rs
@@ -1,3 +1,26 @@
+//! Shows how systems with a similar purpose can be grouped into sets.
+//!
+//! ```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 criteria  _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 4ed3767555..758c00bca2 100644
--- a/examples/ecs/timers.rs
+++ b/examples/ecs/timers.rs
@@ -1,3 +1,5 @@
+//! Illustrates how `Timer`s can be used both as resources and components.
+
 use bevy::{log::info, prelude::*};
 
 fn main() {
diff --git a/examples/games/alien_cake_addict.rs b/examples/games/alien_cake_addict.rs
index 4e3c626575..9506f0cce1 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;
 
@@ -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/breakout.rs b/examples/games/breakout.rs
index 4c777fe325..6721f2c653 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/games/contributors.rs b/examples/games/contributors.rs
index 7cc038e06a..e0b5f4f5dc 100644
--- a/examples/games/contributors.rs
+++ b/examples/games/contributors.rs
@@ -1,3 +1,5 @@
+//! 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};
 use std::{
diff --git a/examples/games/game_menu.rs b/examples/games/game_menu.rs
index 78167cb33a..90fb5fcf4c 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 5e478a35cc..1fbb7af53b 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 d69f2aa1aa..9ad04ff2c8 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 570e60b66b..9bc020a22c 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 0d6becefd9..b235ae0c01 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 e9de57d5b3..1353ed3587 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 5b6ebfa3af..0acb5672c4 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 7b125d205d..7662814e27 100644
--- a/examples/input/mouse_grab.rs
+++ b/examples/input/mouse_grab.rs
@@ -1,3 +1,5 @@
+//! Demonstrates how to grab and hide the mouse cursor.
+
 use bevy::prelude::*;
 
 fn main() {
diff --git a/examples/input/mouse_input.rs b/examples/input/mouse_input.rs
index 6c214b0cf2..918a6713c2 100644
--- a/examples/input/mouse_input.rs
+++ b/examples/input/mouse_input.rs
@@ -1,3 +1,5 @@
+//! Prints mouse button events.
+
 use bevy::prelude::*;
 
 fn main() {
diff --git a/examples/input/mouse_input_events.rs b/examples/input/mouse_input_events.rs
index 16c2a7a74a..547038f40c 100644
--- a/examples/input/mouse_input_events.rs
+++ b/examples/input/mouse_input_events.rs
@@ -1,3 +1,5 @@
+//! Prints all mouse events to the console.
+
 use bevy::{
     input::mouse::{MouseButtonInput, MouseMotion, MouseWheel},
     prelude::*,
diff --git a/examples/input/touch_input.rs b/examples/input/touch_input.rs
index 1616959fc1..b2427aebc4 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 49cecfcd1c..665abd271e 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 9fba61831c..072bed4116 100644
--- a/examples/reflection/generic_reflection.rs
+++ b/examples/reflection/generic_reflection.rs
@@ -1,10 +1,12 @@
+//! Demonstrates how reflection is used with generic 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 24f522614e..8197299cb1 100644
--- a/examples/reflection/reflection.rs
+++ b/examples/reflection/reflection.rs
@@ -1,3 +1,9 @@
+//! 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
+//! features (like scenes).
+
 use bevy::{
     prelude::*,
     reflect::{
@@ -7,9 +13,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 8df74149c7..c621cc786c 100644
--- a/examples/reflection/reflection_types.rs
+++ b/examples/reflection/reflection_types.rs
@@ -1,3 +1,6 @@
+//! This example illustrates how reflection works for simple data structures, like
+//! structs, tuples and vectors.
+
 use bevy::{
     prelude::*,
     reflect::{DynamicList, ReflectRef},
@@ -5,7 +8,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 9dba2f34ff..0c4c4eaf40 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 e7b566dc13..51d6f55aef 100644
--- a/examples/scene/scene.rs
+++ b/examples/scene/scene.rs
@@ -1,6 +1,7 @@
+//! This example illustrates loading 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 2af1d34b85..dd46d6293d 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},
@@ -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 0725bbacc7..37a8c609b6 100644
--- a/examples/shader/compute_shader_game_of_life.rs
+++ b/examples/shader/compute_shader_game_of_life.rs
@@ -1,3 +1,8 @@
+//! 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,
     prelude::*,
@@ -77,6 +82,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>) {
diff --git a/examples/shader/custom_vertex_attribute.rs b/examples/shader/custom_vertex_attribute.rs
index 44ef9d0a18..9453245f8e 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 5be3ad6267..e355ab6faf 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 that enables
+//! conditional compilation in shaders.
+
 use bevy::{
     core_pipeline::Transparent3d,
     pbr::{
diff --git a/examples/shader/shader_instancing.rs b/examples/shader/shader_instancing.rs
index 5698c3325b..b3b04219e4 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 97db298dda..d0eae8481f 100644
--- a/examples/shader/shader_material.rs
+++ b/examples/shader/shader_material.rs
@@ -1,3 +1,5 @@
+//! Illustrates creating a custom material and a shader that uses it.
+
 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 7e405157ce..c09ea8b2ba 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 1adacc7606..ebe30ee49b 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 358ec81462..e651948d96 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 82f9519e20..9c996e9a40 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 measure performance realistically, be sure to run this in release mode.
+//! `cargo run --example many_cubes --release`
+//!
+//! 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.
+//!
+//! 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/stress_tests/many_lights.rs b/examples/stress_tests/many_lights.rs
index 6fe6f91297..d0b765d15d 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},
diff --git a/examples/stress_tests/many_sprites.rs b/examples/stress_tests/many_sprites.rs
index ede9934aa3..8ef12d9ae5 100644
--- a/examples/stress_tests/many_sprites.rs
+++ b/examples/stress_tests/many_sprites.rs
@@ -1,3 +1,9 @@
+//! 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.
+
 use bevy::{
     diagnostic::{FrameTimeDiagnosticsPlugin, LogDiagnosticsPlugin},
     math::Quat,
@@ -9,10 +15,9 @@ 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()
+        // 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)
diff --git a/examples/stress_tests/transform_hierarchy.rs b/examples/stress_tests/transform_hierarchy.rs
index 360f992f12..8dec698f95 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 eceade01f4..1dbcc115fd 100644
--- a/examples/tools/scene_viewer.rs
+++ b/examples/tools/scene_viewer.rs
@@ -1,3 +1,9 @@
+//! 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.
+
 use bevy::{
     asset::{AssetServerSettings, LoadState},
     gltf::Gltf,
@@ -151,6 +157,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 4afa84e417..2323c9c86a 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 25dde970b4..5998fc163d 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.
diff --git a/examples/transforms/scale.rs b/examples/transforms/scale.rs
index 09e6a265f2..fd48fea98c 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 e35f43445c..c57856ff53 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 e61dc76f25..6a709a17ab 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 60269a1f46..b688da0476 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 b598e70c31..18b7aa1635 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 b7d62b5fc5..70490ffece 100644
--- a/examples/ui/text.rs
+++ b/examples/ui/text.rs
@@ -1,11 +1,13 @@
+//! 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},
     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 a40f915214..1c3c63503b 100644
--- a/examples/ui/text_debug.rs
+++ b/examples/ui/text_debug.rs
@@ -1,10 +1,11 @@
+//! Shows various text layout options.
+
 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 30734a87de..f99812c95e 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 b7813ee2c3..62db50cda6 100644
--- a/examples/window/clear_color.rs
+++ b/examples/window/clear_color.rs
@@ -1,3 +1,7 @@
+//! 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::*;
 
 fn main() {
diff --git a/examples/window/low_power.rs b/examples/window/low_power.rs
index 6ecd9ff4cc..e84a5be73d 100644
--- a/examples/window/low_power.rs
+++ b/examples/window/low_power.rs
@@ -1,3 +1,8 @@
+//! 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 +11,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 a0d168c570..3d2125febc 100644
--- a/examples/window/multiple_windows.rs
+++ b/examples/window/multiple_windows.rs
@@ -1,3 +1,5 @@
+//! Uses two windows to visualize a 3D model from different angles.
+
 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 cea0a0f3e8..cb428d80e1 100644
--- a/examples/window/scale_factor_override.rs
+++ b/examples/window/scale_factor_override.rs
@@ -1,6 +1,8 @@
+//! This example illustrates how to override the window scale factor imposed by the
+//! operating system.
+
 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 55de3fbf96..3be9efa8c5 100644
--- a/examples/window/transparent_window.rs
+++ b/examples/window/transparent_window.rs
@@ -1,5 +1,9 @@
-/// 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};
 
 fn main() {
diff --git a/examples/window/window_settings.rs b/examples/window/window_settings.rs
index 85beb371e2..ef11098faa 100644
--- a/examples/window/window_settings.rs
+++ b/examples/window/window_settings.rs
@@ -1,6 +1,8 @@
+//! Illustrates how to change window settings and shows how to affect
+//! the mouse pointer in various ways.
+
 use bevy::{prelude::*, window::PresentMode};
 
-/// This example illustrates how to customize the default window settings
 fn main() {
     App::new()
         .insert_resource(WindowDescriptor {