From dad9c05234302c593e03614bcc7c4d72dea701c3 Mon Sep 17 00:00:00 2001
From: Elijah Voigt <elijah.caine.mv@gmail.com>
Date: Mon, 4 Aug 2025 22:00:31 -0700
Subject: [PATCH] Doc strings for the batches + children observer pattern

---
 src/bin/flappy/main.rs | 17 ++++++++++++++---
 1 file changed, 14 insertions(+), 3 deletions(-)

diff --git a/src/bin/flappy/main.rs b/src/bin/flappy/main.rs
index 42179d1..41e0d70 100644
--- a/src/bin/flappy/main.rs
+++ b/src/bin/flappy/main.rs
@@ -184,6 +184,13 @@ fn init_first_batches(
     commands.spawn(Batch(4));
 }
 
+/// We have the concept of an environment "batch" which contains:
+/// * The ground obstacle
+/// * The pipe obstacle
+/// * The pipe scoring sensor
+///
+/// These are all populated via `OnAdd` observers for the respected components.
+/// This makes it much more concise to spawn each part of the environment.
 fn populate_batch(
     trigger: Trigger<OnAdd, Batch>,
     batches: Query<&Batch>,
@@ -207,6 +214,8 @@ fn populate_batch(
         });
 }
 
+/// The ground population spawns a center peace and two pieces of ground
+/// to the left and right of the center.
 fn populate_ground(
     trigger: Trigger<OnAdd, Ground>,
     grounds: Query<&Ground>,
@@ -223,6 +232,8 @@ fn populate_ground(
     ));
 }
 
+/// Based on if this is a Top or Bottom pipe the placement changes
+/// Otherwise this just spawns in the center of the batch.
 fn populate_pipe(
     trigger: Trigger<OnAdd, Pipe>,
     pipes: Query<&Pipe>,
@@ -242,6 +253,8 @@ fn populate_pipe(
     ));
 }
 
+/// The hitbox should cover the entire height of the screen so if the player
+/// passes between the pipes it registers a point
 fn populate_hitbox(
     trigger: Trigger<OnAdd, Hitbox>,
     mut commands: Commands,
@@ -268,6 +281,7 @@ struct PipeComponents {
     mesh: Mesh2d,
 }
 
+/// Initialize some materials and meshes used by the environment obstacles
 fn init_obstacle_assets(
     mut meshes: ResMut<Assets<Mesh>>,
     mut materials: ResMut<Assets<ColorMaterial>>,
@@ -413,9 +427,6 @@ fn un_pause_game(mut next: ResMut<NextState<PlayerState>>) {
     next.set(PlayerState::Alive);
 }
 
-// TODO: Create floor (and ceiling?)
-// Q: Move bird + camera or move world around bird & camera?
-// TODO: Obstacles
 #[derive(Component, Clone, Event)]
 struct Flap;