Updated documentation: Fraction, PandigitalChecker and PokerHand.

src/utils/objects/fraction.rs

@@ -1,33 +1,52 @@
 use crate::utils;
 
-/// Rational numbers.
+/// Rational numbers stored as a pair of `Long`s.
 #[derive(Clone)]
 pub struct Fraction {
     numerator: utils::Long,
     denominator: utils::Long,
 }
+
 impl Fraction {
+
+    /// Construct a rational number.
+    ///
+    /// * `numerator`
+    /// * `denominator`
+    ///
+    /// Returns a rational number which is the ratio of the given numbers. It
+    /// is not reduced to its lowest form.
     pub fn from(numerator: u32, denominator: u32) -> Fraction {
         Fraction {
             numerator: utils::Long::from(numerator),
             denominator: utils::Long::from(denominator),
         }
     }
+
+    /// Convert the rational number into its reciprocal.
     pub fn invert(&mut self) {
         std::mem::swap(&mut self.numerator, &mut self.denominator);
     }
+
+    /// Obtain the number of decimal digits of the numerator and denominator.
+    /// Mirrors the method of the same name of `Long`.
     pub fn len(&self) -> (usize, usize) {
         (self.numerator.len(), self.denominator.len())
     }
+
+    /// Calculate the sum of all decimal digits of the numerator and
+    /// denominator. Mirrors the method of the same name of `Long`.
     pub fn sum(&self) -> (i64, i64) {
         (self.numerator.sum(), self.denominator.sum())
     }
 }
+
 impl std::ops::AddAssign<u32> for Fraction {
     fn add_assign(&mut self, other: u32) {
         self.numerator += &(&self.denominator * other);
     }
 }
+
 impl std::ops::Add<u32> for &Fraction {
     type Output = Fraction;
     fn add(self, other: u32) -> Fraction {
@@ -36,6 +55,7 @@ impl std::ops::Add<u32> for &Fraction {
         result
     }
 }
+
 impl std::fmt::Display for Fraction {
     fn fmt(&self, f: &mut std::fmt::Formatter) -> std::fmt::Result {
         write!(f, "{}/{}", self.numerator, self.denominator)

src/utils/objects/pandigital_checker.rs

@@ -1,23 +1,33 @@
 use crate::utils;
 
-/// Check whether a bunch of numbers are pandigital with respect to the given
-/// range.
+/// Record the occurrences of all digits in a given range. Used to check
+/// whether a bunch of numbers are pandigital with respect to that range.
 pub struct PandigitalChecker {
     seen: [bool; 10],
     min_digit: usize,
     max_digit: usize,
 }
+
 impl PandigitalChecker {
+
+    /// Construct a pandigital checker for digits in the given range.
+    ///
+    /// * `min_digit`
+    /// * `max_digit`
     pub fn new(min_digit: usize, max_digit: usize) -> PandigitalChecker {
         PandigitalChecker {
             seen: [false; 10],
             min_digit,
             max_digit,
         }
     }
+
+    /// Clear the state of the pandigital checker, so that it behaves as if it
+    /// were newly constructed.
     pub fn renew(&mut self) {
         self.seen = [false; 10];
     }
+
     /// Update the internal array with the digits of a given number.
     ///
     /// * `num` Number to update with.
@@ -34,8 +44,10 @@ impl PandigitalChecker {
         }
         true
     }
-    /// Check whether all digits in the range have been seen. This indicates
-    /// pandigitality only if used in tandem with the above method.
+
+    /// Check whether all digits in the range have been seen. The result
+    /// indicates pandigitality only all previous calls to `update` returned
+    /// `true` and this method returns `true`.
     pub fn check(&self) -> bool {
         self.seen
             .iter()

src/utils/objects/poker_hand.rs

@@ -7,6 +7,7 @@ pub struct PokerHand {
     // Used to rank this hand on an arbitrary scale. Higher is better.
     score: i32,
 }
+
 impl PokerHand {
     const HIGH_CARD: i32 = 0;
     const ONE_PAIR: i32 = 1 << 16;
@@ -19,7 +20,12 @@ impl PokerHand {
     const STRAIGHT_FLUSH: i32 = 8 << 16;
     const ROYAL_FLUSH: i32 = 9 << 16;
 }
+
 impl PokerHand {
+
+    /// Construct a hand of poker. As an example, to represent 8 of clubs, 10
+    /// of spades, king of clubs, 9 of hearts and 4 of spades, the input shall
+    /// be `["8C", "TS", "KC", "9H", "4S"]`.
     pub fn new(hand: &[&str]) -> PokerHand {
         let hand = hand
             .iter()
@@ -41,6 +47,8 @@ impl PokerHand {
         poker_hand.calculate_score();
         poker_hand
     }
+
+    /// Assign an arbitrary score to the hand of poker.
     fn calculate_score(&mut self) {
         // Sorting the cards by descending order of value makes analysing them
         // easier.
@@ -138,6 +146,7 @@ impl PokerHand {
         self.score = PokerHand::HIGH_CARD;
     }
 }
+
 impl Ord for PokerHand {
     fn cmp(&self, other: &PokerHand) -> std::cmp::Ordering {
         let compare = self.score.cmp(&other.score);
@@ -153,6 +162,7 @@ impl Ord for PokerHand {
         std::cmp::Ordering::Equal
     }
 }
+
 impl PartialOrd for PokerHand {
     fn partial_cmp(&self, other: &PokerHand) -> Option<std::cmp::Ordering> {
         Some(self.cmp(other))