From 439b787040fc6ac2f5dc289ab92b632599ebffb7 Mon Sep 17 00:00:00 2001
From: Aryadev Chavali <aryadev@aryadevchavali.com>
Date: Thu, 2 Apr 2026 06:06:16 +0100
Subject: [PATCH] modes:pair: add doc string for Pair::new

---
 src/modes/pair.rs | 6 ++++++
 1 file changed, 6 insertions(+)

diff --git a/src/modes/pair.rs b/src/modes/pair.rs
index f7050ba..3a355fc 100644
--- a/src/modes/pair.rs
+++ b/src/modes/pair.rs
@@ -5,6 +5,12 @@ use crate::helper::ordered;
 pub struct Pair(Card, Card);
 
 impl Pair {
+    /** Create a new pair utilising two cards, `c1` and `c2`.  Will return None
+    if a Pair cannot be constructed out of the two cards.
+
+    NOTE: By construction, if the Pair includes a Joker, that Joker will be the
+    first member of the pair.
+     */
     fn new(c1: Card, c2: Card) -> Option<Pair> {
         // Order the cards.  This means if xor(c1 is joker, c2 is joker) c1 will
         // be that joker.