--- a/src/deck.rs	Tue Jan 31 23:25:50 2023 +0100
+++ b/src/deck.rs	Sat Feb 04 22:46:13 2023 +0100
@@ -1,11 +1,19 @@
-/*** Deck ****/
+/// This is the implementation of a Deck of cards.
+/// There are two basic kinds:
+/// 1. The Game Deck, automatically generated 104 cards.
+/// 2. Any Deck-type pile, like the hand of a Player.
+/// Descks can be shuffled, cards pushed to bottom and
+/// pulled from top. Maybe others, too.
+/// 
+
 use std::collections::VecDeque;
-
 use rand::Rng;
 
+/// We reference [`Card`]s
 use crate::card::Card;
 
 #[derive(Debug)]
+/// A Deck is an ordered two-ended vector (`VecDeque`) of [`Card`]s.
 pub(crate) struct Deck {
     content: VecDeque<Card>,
 }
@@ -39,10 +47,14 @@
         // * kgb: half the deck, take 1..4 cards sequentially from each
         // * grin: take 1..6 from front and put at bottom
 
-        // naive shuffle: exchange random cards
-        for _i in 1..=500 {
+        // naive shuffle: exchange <n> random cards
+        for _ in 1..=500 {
+            // Generate two random positions of cards in Deck
             let c1 = rng.gen_range(0 .. self.content.len());
             let c2 = rng.gen_range(0 .. self.content.len());
+            // If it's not the same card we swap them in the `content` vector.
+            // The `swap()` funtion handles ownership and does not angry 
+            // the borrow checker.
             if c1 != c2 {
                 self.content.swap(c1, c2);
             }
@@ -72,6 +84,8 @@
         self.content.len()
     }
 
+    /// Take a card from inside of the Deck.
+    /// Using an illegal index will `panic!()`, so don't.
     fn _get_nth( &mut self, n: usize ) -> Card {
         if let Some(c) = self.content.remove(n) {
             c