From 414e523ba43578d26c188e2be7c5304c726c4192 Mon Sep 17 00:00:00 2001 From: Aryadev Chavali Date: Tue, 14 Apr 2026 16:59:11 +0100 Subject: [PATCH] *: move from /*** */ doc-comments to /// --- src/card/impls.rs | 27 +++++++++++++-------------- src/card/iters.rs | 9 +++++++++ src/helper.rs | 18 +++++++++--------- src/modes/mod.rs | 16 +++++++--------- src/modes/single.rs | 11 +++++------ src/modes/triple.rs | 14 +++++++------- 6 files changed, 50 insertions(+), 45 deletions(-) diff --git a/src/card/impls.rs b/src/card/impls.rs index 257b4d6..1679de1 100644 --- a/src/card/impls.rs +++ b/src/card/impls.rs @@ -6,15 +6,15 @@ ExactSizeIterator => Map> is not an ESI. But Range is an ESI. */ impl Rank { - /** Generate an iterator over all ranks. */ + /// Generate an iterator over all ranks. pub fn iter_all() -> impl ExactSizeIterator { (0i32..13) .map(|n| n as i64) .map(|n| Rank::try_from(n).unwrap()) } - /** Generate an iterator over all cards within a rank, ordered by Suit. The - cards are all default initialised w.r.t. deck (0).*/ + /// Generate an iterator over all cards within a rank, ordered by Suit. The + /// cards are all default initialised w.r.t. deck (0). pub fn cards(self) -> impl ExactSizeIterator { let n = self as i32; ((n * 4)..((n + 1) * 4)).map(|x| Card::from(x as i64)) @@ -22,13 +22,13 @@ impl Rank { } impl Suit { - /** Generate an iterator over all suits. */ + /// Generate an iterator over all suits. pub fn iter_all() -> impl ExactSizeIterator { (0i32..4).map(|n| Suit::try_from(n as i64).unwrap()) } - /** Generate an iterator over all cards within a suit, ordered by Rank. The - cards are all default initialised in terms of deck (0).*/ + /// Generate an iterator over all cards within a suit, ordered by Rank. The + /// cards are all default initialised in terms of deck (0). pub fn cards(self) -> impl ExactSizeIterator { Rank::iter_all().map(move |rank| Card::make_playing_card(0, rank, self)) } @@ -45,8 +45,8 @@ impl PlayingCard { (rank * 4) + suit } - /** Generate an iterator over all Playing Cards in the `nth` deck. By - construction this is in ascending order. */ + /// Generate an iterator over all Playing Cards in the `nth` deck. By + /// construction this is in ascending order. pub fn iter_all(n: i64) -> impl ExactSizeIterator { (0i32..52) .map(|x| x as i64) @@ -90,12 +90,11 @@ impl Card { } } - /** Generate an iterator over a `n` decks of Cards. Each deck is - concatenated together. By construction, each "deck" of the iterator is in - ascending order. - - Note that each deck gets two jokers. - */ + /// Generate an iterator over `n` decks of Cards. Each deck is concatenated + /// together. By construction, each "deck" of the iterator is in ascending + /// order. + /// + /// Note that each deck gets two jokers. pub fn iter_all(n: i64) -> impl Iterator { // NOTE: I cannot make this into an ExactSizeIterator using the i32 // trick. Chain is not an ESI, nor is FlatMapU> diff --git a/src/card/iters.rs b/src/card/iters.rs index fe6b107..177a14c 100644 --- a/src/card/iters.rs +++ b/src/card/iters.rs @@ -1,10 +1,14 @@ use crate::card::{Card, PlayingCard, Rank, Suit}; +/// Excessively simple card iterator. pub struct CardIterator(Card); impl Iterator for CardIterator { type Item = Card; + /// Generate the next card in the deck based on the current state of the + /// CardIterator. Iteration terminates at the 2 of Spades for the current + /// deck. fn next(&mut self) -> Option { match self.0 { Card::Joker(_) => None, @@ -25,6 +29,9 @@ impl Iterator for CardIterator { } impl DoubleEndedIterator for CardIterator { + /// Generate the previous card in the deck based on the current state of the + /// CardIterator. Iteration terminates at the 3 of Diamonds for the current + /// deck. fn next_back(&mut self) -> Option<::Item> { match self.0 { Card::Joker(_) => None, @@ -45,6 +52,8 @@ impl DoubleEndedIterator for CardIterator { } impl Card { + /// Create a CardIterator from the current card, moving the card in the + /// process. pub fn into_iter(self) -> CardIterator { CardIterator(self) } diff --git a/src/helper.rs b/src/helper.rs index d0854f8..817a530 100644 --- a/src/helper.rs +++ b/src/helper.rs @@ -1,13 +1,13 @@ -/** Given an array of arguments, return them sorted. -Best utilised with array destructuring. */ +/// Given an array of arguments, return them sorted. Best utilised with array +/// destructuring. pub fn ordered(mut xs: [T; N]) -> [T; N] { xs.sort(); xs } -/** An iterator adaptor (derived from ExactSizedIterator) which has a guaranteed -compile time size, allowing for collection of an iterator into a stack allocated -array. */ +/// An iterator adaptor (derived from ExactSizedIterator) which has a guaranteed +/// compile time size, allowing for collection of an iterator into a stack +/// allocated array. pub trait ExactSizedArr: ExactSizeIterator + Sized where I: Default, @@ -21,7 +21,7 @@ where } } -/** Default implementation of ExactSizedArr for any ExactSizeIterator. */ +/// Default implementation of ExactSizedArr for any ExactSizeIterator. impl ExactSizedArr for I where T: Default + Copy + Clone, @@ -29,9 +29,9 @@ where { } -/** A macro which generates Eq, PartialEq, and PartialOrd implementations for -some given type. These implementations are dependent on Ord already being -implemented for that type. */ +/// A macro which generates Eq, PartialEq, and PartialOrd implementations for +/// some given type. These implementations are dependent on Ord already being +/// implemented for that type. macro_rules! impl_cmp_eq_on_ord { ($type:ident) => { impl PartialEq for $type { diff --git a/src/modes/mod.rs b/src/modes/mod.rs index 1861b74..a7b4785 100644 --- a/src/modes/mod.rs +++ b/src/modes/mod.rs @@ -17,9 +17,8 @@ pub trait Hand: Ord { !self.is_proper() } - /** Given two instances of a Hand (`self` and `other`), verify if `self` - footstools `other`. - */ + /// Given two instances of a Hand (`self` and `other`), verify if `self` + /// footstools `other`. fn footstool(&self, other: &Self) -> Footstool; } @@ -29,12 +28,11 @@ mod tests { use super::*; - /** Given two hands, assert that applying a footstool both ways fits a - recognised basic pattern for footstools (in a generic sense). Return the - results of the two footstool checks (x on y, y on x). - - Obviously may panic. - */ + /// Given two hands, assert that applying a footstool both ways fits a + /// recognised basic pattern for footstools (in a generic sense). Return + /// the results of the two footstool checks (x on y, y on x). + /// + /// Obviously may panic. pub fn test_footstool(x: &T, y: &T) -> (Footstool, Footstool) where T: Hand + Copy + Display + Debug, diff --git a/src/modes/single.rs b/src/modes/single.rs index b879076..338c8d1 100644 --- a/src/modes/single.rs +++ b/src/modes/single.rs @@ -4,12 +4,11 @@ use crate::card::Card; pub struct Single(Card); impl Single { - /** Create a new single from a card `c`. Will return None if a Single - cannot be constructed from that card. - - The only situation where a card cannot be converted into a Single is if it's - a Joker. - */ + /// Create a new single from a card `c`. Will return None if a Single + /// cannot be constructed from that card. + /// + /// The only situation where a card cannot be converted into a Single is if + /// it's a Joker. pub fn new(c: Card) -> Option { matches!(c, Card::PlayingCard(_)).then_some(Single(c)) } diff --git a/src/modes/triple.rs b/src/modes/triple.rs index 8c3b853..35de6ad 100644 --- a/src/modes/triple.rs +++ b/src/modes/triple.rs @@ -4,13 +4,13 @@ use crate::{card::Card, helper::ordered}; pub struct Triple(Card, Card, Card); impl Triple { - /** Create a new triple utilising 3 cards: `c1`, `c2`, and `c3`. Will - return None iff a Triple cannot be constructed out of those 3 cards. - - NOTE: By construction, if a triple includes 1 Joker, then Triple::0 is that - joker. If a triple includes 2 jokers, then Triple::0 and Triple::1 are - those jokers. This means Triple::2 will always be a valid playing card. - */ + /// Create a new triple utilising 3 cards: `c1`, `c2`, and `c3`. Will + /// return None iff a Triple cannot be constructed out of those 3 cards. + /// + /// NOTE: By construction, if a triple includes 1 Joker, then Triple::0 is + /// that joker. If a triple includes 2 jokers, then Triple::0 and Triple::1 + /// are those jokers. This means Triple::2 will always be a valid playing + /// card. pub fn new(c1: Card, c2: Card, c3: Card) -> Option { let [c1, c2, c3] = ordered([c1, c2, c3]);