doc: Include missing doc comments

Author: balintkissdev

src/app.rs

@@ -1,8 +1,4 @@
-use std::{
-    collections::HashMap,
-    error::Error,
-    time::Duration,
-};
+use std::{collections::HashMap, error::Error, time::Duration};
 
 use cgmath::{InnerSpace, Vector2};
 use tokio::task::JoinHandle;
@@ -80,6 +76,9 @@ struct App<'a> {
     gui: Option<Gui>,
     client_session: Option<ClientSession>,
     connection_task: Option<ConnectionTaskHandle>,
+    // Pushing pressed keys from event loop into this collection and processing in update() makes
+    // movement continous. Naively checking for key press during event consumption leads to choppy
+    // movement.
     input_state: InputState,
     local_player: Player,
     camera_pos: Vector2<f32>,
@@ -107,7 +106,15 @@ impl<'a> App<'a> {
     }
 
     fn run(&mut self, event_loop: &mut EventLoop<()>) {
+        // Frame-rate independent loop with fixed update, variable framerate.
+        //
+        // A naive calculation and passing of a deltaTime introduces floating point
+        // precision errors, leading to choppy camera movement and unstable logic
+        // even on high framerate. Here, think of it as renderer dictating time, and
+        // logic update adapting to it.
         let mut previous_time = std::time::Instant::now();
+        // How much application "clock" is behind real time. Also known as
+        // "accumulator"
         let mut lag: f32 = 0.0;
         loop {
             let current_time = std::time::Instant::now();
@@ -239,6 +246,7 @@ impl<'a> App<'a> {
                 let base_speed = 10.0;
                 let mut direction = cgmath::vec2(0.0, 0.0);
 
+                // Apply input
                 if self.input_state[InputEvent::MoveUp] {
                     direction.y -= 1.0;
                 }
@@ -257,19 +265,23 @@ impl<'a> App<'a> {
                     direction = direction.normalize();
                 }
 
+                // Move player
                 self.local_player.velocity = direction * base_speed;
                 self.local_player.pos += self.local_player.velocity;
                 globals::clamp_player_to_bounds(&mut self.local_player);
 
+                // Move camera
                 self.move_camera();
 
+                // Message server
                 if self.local_player.velocity != cgmath::vec2(0.0, 0.0) {
                     self.client_session
                         .as_ref()
                         .unwrap()
                         .send_pos(&self.local_player);
                 }
 
+                // Server healthcheck
                 if !self.client_session.as_ref().unwrap().is_server_alive() {
                     eprintln!("Connection to server was lost");
                     self.client_session = None;
@@ -303,6 +315,9 @@ impl<'a> App<'a> {
 }
 
 impl ApplicationHandler for App<'_> {
+    // It is recommended for winit applications to create window and initialize their graphics context
+    // after the first WindowEvent::Resumed even is received. There are systems that won't allow
+    // applications to create a renderer until that.
     fn resumed(&mut self, event_loop: &ActiveEventLoop) {
         let (window, renderer, gui) = Renderer::create_graphics(&event_loop);
 
@@ -372,6 +387,7 @@ impl ApplicationHandler for App<'_> {
             _ => (),
         }
 
+        // Forward rest of events to GUI
         gui.handle_events(&window, &event);
     }
 }

src/client.rs

@@ -12,6 +12,9 @@ use crate::{
     Player, PlayerID,
 };
 
+// Non-blocking channels are used for lock-free message passing from sync main thread to async
+// context and between multiple async tasks.
+// TODO: Research how to handle backpressure
 type ChannelSender = mpsc::UnboundedSender<String>;
 type ChannelReceiver = mpsc::UnboundedReceiver<String>;
 
@@ -20,20 +23,27 @@ pub struct ClientSession {
     send_tx: ChannelSender,
     listen_task: JoinHandle<()>,
     send_task: JoinHandle<()>,
+    /// The local player associated with the client
     session_player: Player,
+    /// Last ping time used for initiating timeout when server is unavailable
     last_ping: std::time::Instant,
 }
 
 pub type ClientSessionResult = Result<ClientSession, Box<dyn Error + Send + Sync>>;
 
 impl ClientSession {
+    /// Bind socket, initiate handshake procedure to server and setup messaging channels.
+    /// Connection and handshake are retried until timeout.
     pub async fn new(server_address: String) -> ClientSessionResult {
         match tokio::time::timeout(globals::CONNECTION_TIMEOUT_SEC, async {
+            // Socket bind
             let client_socket = UdpSocket::bind("0.0.0.0:0").await?;
             let client_socket = Arc::new(client_socket);
 
+            // Server connect
             let session_player = join_server(&client_socket, &server_address).await?;
 
+            // Message handlers
             let (listen_tx, listen_rx) = mpsc::unbounded_channel();
             let (send_tx, send_rx) = mpsc::unbounded_channel();
             let listen_task = tokio::spawn(listen_handler(client_socket.clone(), listen_tx));
@@ -71,6 +81,7 @@ impl ClientSession {
     pub fn receive_server_response(&mut self) -> Result<String, TryRecvError> {
         match self.listen_rx.try_recv() {
             Ok(response) => {
+                // Update last ping
                 if let Ok(Message::Ping) = Message::deserialize(&response) {
                     self.last_ping = std::time::Instant::now();
                 }
@@ -81,12 +92,14 @@ impl ClientSession {
     }
 
     pub fn send_pos(&self, player: &Player) {
+        // TODO: Avoid position self-reporting
         let _ = self
             .send_tx
             .send(Message::Position(player.id, player.pos).serialize());
     }
 
     pub fn is_server_alive(&self) -> bool {
+        // There's no need for separate timeout countdown timer
         self.last_ping.elapsed() < globals::CONNECTION_TIMEOUT_SEC
     }
 
@@ -111,11 +124,13 @@ async fn join_server(
     let handshake_msg = Message::Handshake.serialize();
     // Loop abort happens on timeout in ClientSession::new()
     loop {
+        // Send handshake
         client_socket
             .send_to(handshake_msg.as_bytes(), server_address)
             .await?;
         message::trace(format!("Sent: {handshake_msg}"));
 
+        // Wait for ACK
         match receive_with_retry_timeout(client_socket).await {
             Ok(response) => {
                 if let Ok(Message::Ack(new_id, new_color)) = Message::deserialize(&response) {

src/fsm.rs

@@ -1,6 +1,7 @@
+/// Parameter used for first connection establishment
 #[derive(Clone, Copy)]
 pub enum SessionMode {
-    CreateServer,
+    CreateServer,   /// Peer-hosted, hybrid server-client session
     ConnectAsClientOnly,
 }
 
@@ -21,7 +22,7 @@ pub enum State {
 /// state like a stack. Basically just a thin wrapper around a Vec, which is recommended for stack
 /// data structures by https://doc.rust-lang.org/std/collections/index.html#use-a-vec-when
 ///
-/// There are third-party crates like rust_fsm, but not necessary to include too much crates.
+/// There are third-party crates like rust_fsm, but I prefer not to include too many crates.
 pub struct StateMachine {
     state_stack: Vec<State>,
 }

src/gui.rs

@@ -8,6 +8,7 @@ use winit::{event::WindowEvent, event_loop::ActiveEventLoop};
 
 use crate::{fsm, globals};
 
+/// GUI layer for all dialog boxes and the gameplay log output window.
 pub struct Gui {
     egui_glow: EguiGlow,
     log_messages: String,
@@ -37,17 +38,20 @@ impl Gui {
         }
     }
 
+    /// Forward native window events like input to egui.
     pub fn handle_events(&mut self, window: &winit::window::Window, event: &WindowEvent) {
         let _ = self.egui_glow.on_window_event(&window, &event);
     }
 
+    /// Execute UI code and populate batch before draw call
     pub fn prepare_frame(
         &mut self,
         window: &winit::window::Window,
         state_machine: &mut fsm::StateMachine,
     ) {
         self.egui_glow
             .run(&window, |ctx| match state_machine.peek() {
+                // Starter connection menu
                 Some(fsm::State::Menu) | Some(fsm::State::Connecting { .. }) => show_menu(
                     ctx,
                     state_machine,
@@ -56,33 +60,40 @@ impl Gui {
                     &mut self.status_text,
                     &mut self.status_color,
                 ),
+                // Gameplay state
                 Some(fsm::State::Playing) => show_log(ctx, &self.log_messages),
+                // Disconnect dialog
                 Some(fsm::State::Disconnected) => show_disconnected_dialog(
                     ctx,
                     state_machine,
                     &mut self.log_messages,
                     &mut self.status_text,
                     &mut self.status_color,
                 ),
+                // Quit confirm dialog
                 Some(fsm::State::QuitDialog) => show_quit_dialog(ctx, state_machine),
                 _ => {}
             });
     }
 
+    /// Issue batched draw call
     pub fn draw(&mut self, window: &winit::window::Window) {
         self.egui_glow.paint(&window);
     }
 
+    /// Redirect message to gameplay log window
     pub fn log(&mut self, msg: String) {
         self.log_messages += &format!("{msg}\n");
     }
 
+    /// Error status on connection menu and Disconnected message dialog
     pub fn set_error_status(&mut self, msg: String) {
         self.status_color = Color32::RED;
         self.status_text = msg;
     }
 }
 
+/// Starter connection menu
 fn show_menu(
     ctx: &egui::Context,
     state_machine: &mut fsm::StateMachine,
@@ -102,20 +113,23 @@ fn show_menu(
                 .num_columns(2)
                 .spacing([10.0, 10.0])
                 .show(ui, |ui| {
+                    // Server address textbox
                     ui.label("Server address:");
                     ui.add(TextEdit::singleline(server_hostname).desired_width(150.0));
                     ui.end_row();
 
+                    // Server port number textbox
                     ui.label("Port:");
                     ui.add(TextEdit::singleline(server_port).desired_width(150.0));
                     ui.end_row();
 
+                    // Disable "Connect" button while client is trying to connect
                     let connect_buttons_enabled =
                         !matches!(state_machine.peek(), Some(fsm::State::Connecting { .. }));
+
+                    // "Create server" button
                     let create_button =
                         ui.add_enabled(connect_buttons_enabled, Button::new("Create server"));
-                    let join_button =
-                        ui.add_enabled(connect_buttons_enabled, Button::new("Join server"));
                     if create_button.clicked() {
                         match verify_address_format(server_hostname, server_port) {
                             Ok(_) => {
@@ -132,6 +146,10 @@ fn show_menu(
                             }
                         }
                     }
+
+                    // "Join server" button
+                    let join_button =
+                        ui.add_enabled(connect_buttons_enabled, Button::new("Join server"));
                     if join_button.clicked() {
                         match verify_address_format(server_hostname, server_port) {
                             Ok(_) => {
@@ -148,9 +166,12 @@ fn show_menu(
                             }
                         }
                     }
+
+                    // Status label
                     ui.colored_label(*status_color, status_text);
                     ui.end_row();
 
+                    // "Quit" button
                     if ui.button("Quit").clicked() {
                         state_machine.push(fsm::State::QuitDialog);
                     }

src/lib.rs

@@ -59,10 +59,21 @@ pub mod globals {
     pub const WINDOW_SIZE: (u16, u16) = (800, 600);
     pub const WINDOW_TITLE: &str = "Multiplayer game demo by Bálint Kiss";
 
+    /// This is the granularity of how often to update logic and not to be confused
+    /// with framerate limiting or 60 frames per second, because the main loop
+    /// implementation uses a fixed update, variable framerate timestep algorithm.
+    ///
+    /// 60 logic updates per second is a common value used in games.
+    /// - Higher update rate (120) can lead to smoother gameplay, more precise
+    /// control, at the cost of CPU load. Keep mobile devices in mind.
+    /// - Lower update rate (30) reduces CPU load, runs game logic less frequently,
+    /// but can make game less responsive.
     pub const MAX_LOGIC_UPDATE_PER_SEC: f32 = 60.0;
     pub const FIXED_UPDATE_TIMESTEP_SEC: f32 = 1.0 / MAX_LOGIC_UPDATE_PER_SEC;
 
     pub const PLAYER_QUAD_SIZE: f32 = 24.0;
+
+    /// World bounds are relative to origin (0,0)
     pub const WORLD_BOUNDS: WorldBounds = WorldBounds {
         min_x: -1200.0,
         min_y: -1200.0,

src/main.rs

@@ -36,13 +36,14 @@ fn main() -> Result<(), Box<dyn Error>> {
         message::set_trace(true);
     }
 
-    // Application window events, rendering and GUI are in syncronous environment and async code
-    // cannot be called from there. Manage Tokio runtime separately to bridge sync
-    // code with async code easily.
+    // Application window events, rendering, and GUI are in syncronous context where async code
+    // cannot be called directly. Managing Tokio runtime separately instead of relying on
+    // "#[tokio::main]" in order to bridge sync code with async code easily .
     let rt = tokio::runtime::Builder::new_multi_thread()
         .enable_all()
         .build()?;
 
+    // Start a headless server only if option is set.
     if cli.server_only {
         println!("Starting server in headless mode");
         rt.block_on(async {
@@ -62,8 +63,9 @@ fn main() -> Result<(), Box<dyn Error>> {
                 }
             }
         });
-        Ok(())
-    } else {
-        app::run_app(&rt)
+        return Ok(());
     }
+
+    // Run graphical client otherwise.
+    app::run_app(&rt)
 }

src/message.rs

@@ -6,12 +6,26 @@ use crate::{Player, PlayerID};
 
 #[derive(PartialEq)]
 pub enum Message {
+    /// Periodic ping message for server healthcheck
+    // TODO: Extend for client disconnect check
     Ping,
+
+    /// Initial handshake by client on join. Retried on UDP packet loss until timeout.
     Handshake,
+
+    /// Server response to received handshake
     Ack(PlayerID, Vector3<f32>),
+
+    /// Server response notifying all players still remaining on server about player exit so they
+    /// can update their state.
     Leave(PlayerID),
+
+    /// Server's world replication of a single player position
+    /// TODO: Currently sent one-by-one, make it a bulk send instead
     Replicate(Player),
-    // TODO: Avoid clients self-reporting their exact own position and opt for sending input state
+
+    /// Player's position response after movement change.
+    // TODO: Avoid clients self-reporting their exact own position and opt for sending input action
     // instead
     Position(PlayerID, Vector2<f32>),
 }