bevyengine#1934 WIP

.

crates/bevy_ecs/src/component.rs

@@ -35,6 +35,8 @@ impl<T: Send + Sync + 'static> Component for T {}
 /// let mut world = World::default();
 /// world.register_component(ComponentDescriptor::new::<A>(StorageType::SparseSet));
 /// ```
+///
+/// [Example usage.](https://github.com/bevyengine/bevy/blob/latest/bevy_ecs/examples/component_storage.rs)
 #[derive(Debug, Copy, Clone, Eq, PartialEq)]
 pub enum StorageType {
     /// Provides fast and cache-friendly iteration, but slower addition and removal of components.

crates/bevy_ecs/src/event.rs

@@ -118,6 +118,8 @@ enum State {
 /// but can be done by adding your event as a resource instead of using [`App::add_event`].
 ///
 /// [`App::add_event`]: https://docs.rs/bevy/*/bevy/app/struct.App.html#method.add_event
+///
+/// [Example usage.](https://github.com/bevyengine/bevy/blob/latest/bevy_ecs/examples/events.rs)
 #[derive(Debug)]
 pub struct Events<T> {
     events_a: Vec<EventInstance<T>>,
@@ -150,13 +152,21 @@ fn map_instance_event<T>(event_instance: &EventInstance<T>) -> &T {
 }
 
 /// Reads events of type `T` in order and tracks which events have already been read.
+///
+/// [Simple example usage.](https://github.com/bevyengine/bevy/blob/latest/examples/ecs/event.rs)
+///
+/// [Detailed example usage.](https://github.com/bevyengine/bevy/blob/latest/bevy_ecs/examples/events.rs)
 #[derive(SystemParam)]
 pub struct EventReader<'a, T: Component> {
     last_event_count: Local<'a, (usize, PhantomData<T>)>,
     events: Res<'a, Events<T>>,
 }
 
 /// Sends events of type `T`.
+///
+/// [Simple example usage.](https://github.com/bevyengine/bevy/blob/latest/examples/ecs/event.rs)
+///
+/// [Detailed example usage.](https://github.com/bevyengine/bevy/blob/latest/bevy_ecs/examples/events.rs)
 #[derive(SystemParam)]
 pub struct EventWriter<'a, T: Component> {
     events: ResMut<'a, Events<T>>,

crates/bevy_ecs/src/query/filter.rs

@@ -713,6 +713,8 @@ impl_tick_filter!(
     ///
     /// # print_add_name_component.system();
     /// ```
+    ///
+    /// [Example usage.](https://github.com/bevyengine/bevy/blob/latest/bevy_ecs/examples/change_detection.rs)
     Added,
     /// The [`FetchState`] of [`Added`].
     AddedState,
@@ -754,6 +756,10 @@ impl_tick_filter!(
     ///
     /// # print_moving_objects_system.system();
     /// ```
+    ///
+    /// [Simple example usage.](https://github.com/bevyengine/bevy/blob/latest/examples/ecs/component_change_detection.rs)
+    ///
+    /// [Detailed example usage.](https://github.com/bevyengine/bevy/blob/latest/bevy_ecs/examples/change_detection.rs)
     Changed,
     /// The [`FetchState`] of [`Changed`].
     ChangedState,

crates/bevy_input/src/keyboard.rs

@@ -3,6 +3,7 @@ use bevy_app::EventReader;
 use bevy_ecs::system::ResMut;
 
 /// A key input event from a keyboard device
+/// [Example usage.](https://github.com/bevyengine/bevy/blob/latest/examples/input/keyboard_input_event.rs)
 #[derive(Debug, Clone)]
 pub struct KeyboardInput {
     pub scan_code: u32,

crates/bevy_math/src/geometry.rs

@@ -3,6 +3,7 @@ use glam::Vec2;
 use std::ops::{Add, AddAssign, Div, DivAssign, Mul, MulAssign, Sub, SubAssign};
 
 /// A two dimensional "size" as defined by a width and height
+/// [Example usage.](https://github.com/bevyengine/bevy/blob/latest/examples/ui/ui.rs)
 #[derive(Copy, Clone, PartialEq, Debug, Reflect)]
 #[reflect(PartialEq)]
 pub struct Size<T: Reflect + PartialEq = f32> {
@@ -26,6 +27,7 @@ impl<T: Default + Reflect + PartialEq> Default for Size<T> {
 }
 
 /// A rect, as defined by its "side" locations
+/// [Example usage.](https://github.com/bevyengine/bevy/blob/latest/examples/ui/ui.rs)
 #[derive(Copy, Clone, PartialEq, Debug, Reflect)]
 #[reflect(PartialEq)]
 pub struct Rect<T: Reflect + PartialEq> {

crates/bevy_pbr/src/entity.rs

@@ -11,6 +11,7 @@ use bevy_render::{
 use bevy_transform::prelude::{GlobalTransform, Transform};
 
 /// A component bundle for "pbr mesh" entities
+/// [Example usage.](https://github.com/bevyengine/bevy/blob/latest/examples/3d/pbr.rs)
 #[derive(Bundle)]
 pub struct PbrBundle {
     pub mesh: Handle<Mesh>,
@@ -41,6 +42,7 @@ impl Default for PbrBundle {
 }
 
 /// A component bundle for "light" entities
+/// [Example usage.](https://github.com/bevyengine/bevy/blob/latest/examples/3d/pbr.rs)
 #[derive(Debug, Bundle, Default)]
 pub struct PointLightBundle {
     pub point_light: PointLight,

crates/bevy_pbr/src/light.rs

@@ -153,6 +153,7 @@ impl DirectionalLightUniform {
 }
 
 // Ambient light color.
+/// [Example usage.](https://github.com/bevyengine/bevy/blob/latest/examples/3d/load_gltf.rs)
 #[derive(Debug)]
 pub struct AmbientLight {
     pub color: Color,

crates/bevy_pbr/src/material.rs

@@ -4,6 +4,7 @@ use bevy_render::{color::Color, renderer::RenderResources, shader::ShaderDefs, t
 
 /// A material with "standard" properties used in PBR lighting
 /// Standard property values with pictures here https://google.github.io/filament/Material%20Properties.pdf
+/// [Example usage.](https://github.com/bevyengine/bevy/blob/latest/examples/3d/texture.rs)
 #[derive(Debug, RenderResources, ShaderDefs, TypeUuid)]
 #[uuid = "dace545e-4bc6-4595-a79d-c224fc694975"]
 pub struct StandardMaterial {

crates/bevy_render/src/entity.rs

@@ -14,6 +14,7 @@ use bevy_ecs::bundle::Bundle;
 use bevy_transform::components::{GlobalTransform, Transform};
 
 /// A component bundle for "mesh" entities
+/// [Example usage.](https://github.com/bevyengine/bevy/blob/latest/examples/shader/array_texture.rs)
 #[derive(Bundle, Default)]
 pub struct MeshBundle {
     pub mesh: Handle<Mesh>,
@@ -28,6 +29,7 @@ pub struct MeshBundle {
 /// Component bundle for camera entities with perspective projection
 ///
 /// Use this for 3D rendering.
+/// [Example usage.](https://github.com/bevyengine/bevy/blob/latest/examples/3d/3d_scene.rs)
 #[derive(Bundle)]
 pub struct PerspectiveCameraBundle {
     pub camera: Camera,
@@ -74,6 +76,8 @@ impl Default for PerspectiveCameraBundle {
 /// Component bundle for camera entities with orthographic projection
 ///
 /// Use this for 2D games, isometric games, CAD-like 3D views.
+/// [Example usage in 2D.](https://github.com/bevyengine/bevy/blob/latest/examples/3d/orthographic.rs)
+/// [Example usage in 3D.](https://github.com/bevyengine/bevy/blob/latest/examples/3d/orthographic.rs)
 #[derive(Bundle)]
 pub struct OrthographicCameraBundle {
     pub camera: Camera,
@@ -84,6 +88,7 @@ pub struct OrthographicCameraBundle {
 }
 
 impl OrthographicCameraBundle {
+    /// [Example usage](https://github.com/bevyengine/bevy/blob/latest/examples/2d/sprite.rs)
     pub fn new_2d() -> Self {
         // we want 0 to be "closest" and +far to be "farthest" in 2d, so we offset
         // the camera's translation by far and use a right handed coordinate system
@@ -104,6 +109,7 @@ impl OrthographicCameraBundle {
         }
     }
 
+    /// [Example usage](https://github.com/bevyengine/bevy/blob/latest/examples/3d/orthographic.rs)
     pub fn new_3d() -> Self {
         OrthographicCameraBundle {
             camera: Camera {

crates/bevy_render/src/render_graph/base.rs

@@ -15,10 +15,12 @@ use bevy_reflect::Reflect;
 use bevy_window::WindowId;
 
 /// A component that indicates that an entity should be drawn in the "main pass"
+/// [Example usage.](https://github.com/bevyengine/bevy/blob/latest/examples/window/multiple_windows.rs)
 #[derive(Clone, Debug, Default, Reflect)]
 #[reflect(Component)]
 pub struct MainPass;
 
+/// [Example usage.](https://github.com/bevyengine/bevy/blob/latest/examples/3d/msaa.rs)
 #[derive(Debug)]
 pub struct Msaa {
     pub samples: u32,
@@ -31,6 +33,7 @@ impl Default for Msaa {
 }
 
 impl Msaa {
+    /// [Example usage.](https://github.com/bevyengine/bevy/blob/latest/examples/window/multiple_windows.rs)
     pub fn color_attachment(
         &self,
         attachment: TextureAttachment,

examples/README.md

@@ -45,6 +45,7 @@ git checkout v0.4.0
   - [Audio](#audio)
   - [Diagnostics](#diagnostics)
   - [ECS (Entity Component System)](#ecs-entity-component-system)
+  - [Examples inside bevy_ecs sub-crate](#examples-inside-bevy_ecs-sub-crate)
   - [Games](#games)
   - [Input](#input)
   - [Reflection](#reflection)
@@ -171,6 +172,15 @@ Example | File | Description
 `system_sets` | [`ecs/system_sets.rs`](./ecs/system_sets.rs) | Shows `SystemSet` use along with run criterion
 `timers` | [`ecs/timers.rs`](./ecs/timers.rs) | Illustrates ticking `Timer` resources inside systems and handling their state
 
+## Examples inside bevy_ecs sub-crate
+
+Example | File | Description
+--- | --- | ---
+`change_detection` | [`crates/bevy_ecs/examples/change_detecion.rs`](../crates/bevy_ecs/examples/change_detecion.rs) | Detailed example of change detection
+`component_storage` | [`crates/bevy_ecs/examples/component_storage.rs`](../crates/bevy_ecs/examples/component_storage.rs) | Detailed example of different storage mechanisms
+`events` | [`crates/bevy_ecs/examples/events.rs`](../crates/bevy_ecs/examples/events.rs) | Illustrates event creation, activation, and reception
+`resources` | [`crates/bevy_ecs/examples/resources.rs`](../crates/bevy_ecs/examples/resources.rs) | Detailed example of resource creation and usage
+
 ## Games
 
 Example | File | Description