From 29ec8bf219afd460f5e9b1c696cd03d179675481 Mon Sep 17 00:00:00 2001 From: "Christoph J. Scherr" Date: Fri, 2 Aug 2024 15:12:07 +0200 Subject: [PATCH] docs(game): make it clear what some parameters and methods do --- src/game/mod.rs | 30 ++++++++++++++++++++++++++++-- 1 file changed, 28 insertions(+), 2 deletions(-) diff --git a/src/game/mod.rs b/src/game/mod.rs index 6873311..6d53c5b 100644 --- a/src/game/mod.rs +++ b/src/game/mod.rs @@ -49,6 +49,16 @@ impl<'wl, WL: WordList> Game<'wl, WL> { /// # Errors /// /// No Errors + /// + /// # Parameters + /// + /// `length` - how many chars the solution has + /// `precompute` - how many chars the solution has + /// `max_steps` - how many tries the player has + /// `precompute` - how many chars the solution has + /// `wlist` - which wordlist to use + /// `generate_solution` - should the game have a randomly generated solution? + pub fn build( length: usize, precompute: bool, @@ -115,7 +125,8 @@ impl<'wl, WL: WordList> Game<'wl, WL> { Ok(response) } - pub fn evaluate(mut solution: WordData, guess: &Word) -> Evaluation { + /// Generates an [Evaluation] for a given solution and guess. + pub(crate) fn evaluate(mut solution: WordData, guess: &Word) -> Evaluation { let mut evaluation = Vec::new(); let mut status: Status; for (idx, c) in guess.chars().enumerate() { @@ -140,18 +151,25 @@ impl<'wl, WL: WordList> Game<'wl, WL> { Ok(()) } + /// get how many characters the words have for this game pub fn length(&self) -> usize { self.length } + /// get the solution for this game, if the game is aware of one. + /// + /// Consider that games may also be played on other platforms, so the game might not "know" the + /// solution yet. pub fn solution(&self) -> Option<&WordData> { self.solution.as_ref() } + /// get how many guesses have been made already pub fn step(&self) -> usize { self.step } + /// true if the game has finished and no more guesses can be made pub fn finished(&self) -> bool { if self.responses().is_empty() { return false; @@ -159,27 +177,35 @@ impl<'wl, WL: WordList> Game<'wl, WL> { self.responses().last().unwrap().finished() } + /// true if the game has finished and the solution was found pub fn won(&self) -> bool { - if self.responses().is_empty() { + if !self.finished() || self.responses().is_empty() { return false; } self.responses().last().unwrap().won() } + /// get how many tries the player has pub fn max_steps(&self) -> usize { self.max_steps } + + /// get the responses that were already made pub fn responses(&self) -> &Vec { &self.responses } + + /// get the most recent response pub fn last_response(&self) -> Option<&GuessResponse> { self.responses().last() } + /// get the [WordList] for this game pub fn wordlist(&self) -> &WL { self.wordlist } + /// get the [Words](Word) that have already been tried pub(crate) fn made_guesses(&self) -> Vec<&Word> { self.responses.iter().map(|r| r.guess()).collect() }