Doc/module style doc blocks for examples (bevyengine#4438)

# Objective

Provide a starting point for bevyengine#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.

Author: themasch

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() {

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)

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 {

examples/2d/rotation.rs

@@ -1,3 +1,5 @@
+//! Demonstrates rotating entities in 2D using quaternions.
+
 use bevy::{
     core::FixedTimestep,
     math::{const_vec2, Vec3Swizzles},

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() {

examples/2d/sprite.rs

@@ -1,3 +1,5 @@
+//! Displays a single [`Sprite`], created from an image.
+
 use bevy::prelude::*;
 
 fn main() {

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() {

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() {

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() {

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>()

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() {

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() {

examples/3d/load_gltf.rs

@@ -1,3 +1,5 @@
+//! Loads and renders a glTF file as a scene.
+
 use bevy::prelude::*;
 
 fn main() {

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 })

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() {

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 })

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)

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,

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() {

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::*,

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() {

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)

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>>,

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() {

examples/3d/vertex_colors.rs

@@ -1,3 +1,5 @@
+//! Illustrates the use of vertex colors.
+
 use bevy::{prelude::*, render::mesh::VertexAttributeValues};
 
 fn main() {

examples/3d/wireframe.rs

@@ -1,3 +1,5 @@
+//! Showcases wireframe rendering.
+
 use bevy::{
     pbr::wireframe::{Wireframe, WireframeConfig, WireframePlugin},
     prelude::*,

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

examples/animation/animated_fox.rs

@@ -1,3 +1,5 @@
+//! Plays animations from a skinned glTF.
+
 use bevy::prelude::*;
 
 fn main() {

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::*;

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)

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>

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() {

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() {

examples/app/empty.rs

@@ -1,3 +1,5 @@
+//! An empty application (does nothing)
+
 use bevy::prelude::*;
 
 fn main() {

examples/app/empty_defaults.rs

@@ -1,3 +1,5 @@
+//! An empty application with default plugins.
+
 use bevy::prelude::*;
 
 fn main() {

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

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() {

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:

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)