From c8481d35c120ff99213e6ed73ba889e51cac10c5 Mon Sep 17 00:00:00 2001
From: mo8it <mo8it@proton.me>
Date: Tue, 14 May 2024 01:49:22 +0200
Subject: [PATCH] Done documentation

---
 src/progress_bar.rs       | 3 +++
 src/run.rs                | 6 +-----
 src/watch.rs              | 5 +++--
 src/watch/notify_event.rs | 5 +++--
 src/watch/state.rs        | 9 +++++----
 5 files changed, 15 insertions(+), 13 deletions(-)

diff --git a/src/progress_bar.rs b/src/progress_bar.rs
index d6962b8c..4a54170a 100644
--- a/src/progress_bar.rs
+++ b/src/progress_bar.rs
@@ -12,6 +12,7 @@ const MIN_LINE_WIDTH: u16 = WRAPPER_WIDTH + 4;
 const PROGRESS_EXCEEDS_MAX_ERR: &str =
     "The progress of the progress bar is higher than the maximum";
 
+/// Terminal progress bar to be used when not using Ratataui.
 pub fn progress_bar(progress: u16, total: u16, line_width: u16) -> Result<String> {
     use crossterm::style::Stylize;
 
@@ -54,6 +55,8 @@ pub fn progress_bar(progress: u16, total: u16, line_width: u16) -> Result<String
     Ok(line)
 }
 
+/// Progress bar to be used with Ratataui.
+// Not using Ratatui's Gauge widget to keep the progress bar consistent.
 pub fn progress_bar_ratatui(progress: u16, total: u16, line_width: u16) -> Result<Line<'static>> {
     use ratatui::style::Stylize;
 
diff --git a/src/run.rs b/src/run.rs
index ac974143..36899b91 100644
--- a/src/run.rs
+++ b/src/run.rs
@@ -41,11 +41,7 @@ pub fn run(app_state: &mut AppState) -> Result<()> {
 
     match app_state.done_current_exercise(&mut stdout)? {
         ExercisesProgress::AllDone => (),
-        ExercisesProgress::CurrentPending => println!(
-            "Current exercise: {}",
-            app_state.current_exercise().terminal_link(),
-        ),
-        ExercisesProgress::NewPending => println!(
+        ExercisesProgress::CurrentPending | ExercisesProgress::NewPending => println!(
             "Next exercise: {}",
             app_state.current_exercise().terminal_link(),
         ),
diff --git a/src/watch.rs b/src/watch.rs
index 2fbc5337..88a12301 100644
--- a/src/watch.rs
+++ b/src/watch.rs
@@ -14,7 +14,7 @@ use std::{
 use crate::app_state::{AppState, ExercisesProgress};
 
 use self::{
-    notify_event::DebounceEventHandler,
+    notify_event::NotifyEventHandler,
     state::WatchState,
     terminal_event::{terminal_event_handler, InputEvent},
 };
@@ -40,6 +40,7 @@ pub enum WatchExit {
     List,
 }
 
+/// `notify_exercise_names` as None activates the manual run mode.
 pub fn watch(
     app_state: &mut AppState,
     notify_exercise_names: Option<&'static [&'static [u8]]>,
@@ -52,7 +53,7 @@ pub fn watch(
     let _debouncer_guard = if let Some(exercise_names) = notify_exercise_names {
         let mut debouncer = new_debouncer(
             Duration::from_millis(200),
-            DebounceEventHandler {
+            NotifyEventHandler {
                 tx: tx.clone(),
                 exercise_names,
             },
diff --git a/src/watch/notify_event.rs b/src/watch/notify_event.rs
index a2243771..74716409 100644
--- a/src/watch/notify_event.rs
+++ b/src/watch/notify_event.rs
@@ -3,12 +3,13 @@ use std::sync::mpsc::Sender;
 
 use super::WatchEvent;
 
-pub struct DebounceEventHandler {
+pub struct NotifyEventHandler {
     pub tx: Sender<WatchEvent>,
+    /// Used to report which exercise was modified.
     pub exercise_names: &'static [&'static [u8]],
 }
 
-impl notify_debouncer_mini::DebounceEventHandler for DebounceEventHandler {
+impl notify_debouncer_mini::DebounceEventHandler for NotifyEventHandler {
     fn handle_event(&mut self, input_event: DebounceEventResult) {
         let output_event = match input_event {
             Ok(input_event) => {
diff --git a/src/watch/state.rs b/src/watch/state.rs
index abd21fbd..14c3f015 100644
--- a/src/watch/state.rs
+++ b/src/watch/state.rs
@@ -1,7 +1,7 @@
 use anyhow::Result;
 use crossterm::{
     style::{style, Stylize},
-    terminal::size,
+    terminal,
 };
 use std::io::{self, StdoutLock, Write};
 
@@ -84,6 +84,7 @@ impl<'a> WatchState<'a> {
         self.run_current_exercise()
     }
 
+    /// Move on to the next exercise if the current one is done.
     pub fn next_exercise(&mut self) -> Result<ExercisesProgress> {
         if self.done_status == DoneStatus::Pending {
             return Ok(ExercisesProgress::CurrentPending);
@@ -113,7 +114,7 @@ impl<'a> WatchState<'a> {
     }
 
     pub fn render(&mut self) -> Result<()> {
-        // Prevent having the first line shifted.
+        // Prevent having the first line shifted if clearing wasn't successful.
         self.writer.write_all(b"\n")?;
 
         clear_terminal(&mut self.writer)?;
@@ -145,11 +146,11 @@ When you are done experimenting, enter `n` to move on to the next exercise 🦀"
             writeln!(
                 self.writer,
                 "A solution file can be found at {}\n",
-                style(TerminalFileLink(solution_path)).underlined().green()
+                style(TerminalFileLink(solution_path)).underlined().green(),
             )?;
         }
 
-        let line_width = size()?.0;
+        let line_width = terminal::size()?.0;
         let progress_bar = progress_bar(
             self.app_state.n_done(),
             self.app_state.exercises().len() as u16,