Document hand analysis functions in hand.h (#572)

* doxygen

* clang format

* Update round.cFix call to `find_straight_in_played_cards`

* Update straight/flush functions docs in hand.h

* typo

---------

Co-authored-by: MathisMartin31 <mathis.martin31@gmail.com>

include/hand.h

@@ -216,24 +216,53 @@ void sort_cards(void);
 // Hand Contents Analysis
 
 /**
- * Finds the largest flush (set of cards with the same suit) in the given array of played cards.
- * Marks the cards belonging to the best flush in the out_selection array.
+ * @brief Finds the best flush (set of cards with the same suit) in the given array of played
+ *         cards.
+ *
+ * Normally a Flush is made of 5 cards of the same suit, but this function takes into account
+ * the Four Fingers joker which allows for Flushes made of 4 cards only.
+ *
+ * The cards belonging to that flush will be marked as selected in the out_selection array.
  *
  * @param played        Array of pointers to CardObject representing played cards.
  * @param top           Index of the top of the played stack.
  * @param min_len       Minimum number of cards required for a flush.
  * @param out_selection Output array of bools; set to true for cards in the best flush, false
- * otherwise.
+ *                       otherwise.
+ *
  * @return              The number of cards in the best flush found, or 0 if no flush meets min_len.
  */
 int find_flush_in_played_cards(CardObject** played, int top, int min_len, bool* out_selection);
-int find_straight_in_played_cards(
-    CardObject** played,
-    int top,
-    bool shortcut_active,
-    int min_len,
-    bool* out_selection
-);
+
+/**
+ * @brief Finds the best straight in the given array of played cards.
+ *
+ * Normally, a Straight is a set of 5 cards with sequential ranks, but this function takes into
+ * account the Four Fingers and Shortcut jokers, which respectively allow for Straights made of
+ * 4 cards and with gaps of 1 rank between two cards.
+ *
+ * The cards belonging to that straight will be marked as selected in the out_selection array.
+ *
+ * @param played        Array of pointers to CardObject representing played cards.
+ * @param top           Index of the top of the played stack.
+ * @param min_len       Minimum number of cards required for a straight.
+ * @param out_selection Output array of bools; set to true for cards in the best straight, false
+ *                       otherwise.
+ *
+ * @return              The number of cards in the best straight found, or 0 if no straight meets
+ *                       min_len.
+ */
+int find_straight_in_played_cards(CardObject** played, int top, int min_len, bool* out_selection);
+
+/**
+ * @brief This is used for the special case in "Four Fingers" where you can add a pair into a
+ *         straight (e.g. AA234 should score all 5 cards)
+ *
+ * @param played    Array of pointers to CardObject representing played cards.
+ * @param top       Index of the top of the played stack.
+ * @param selection In/Out array of bools; cards from a straight are already set to true, so we
+ *                   add to those the leftover ones that form a pair with an already selected card.
+ */
 void select_paired_cards_in_hand(CardObject** played, int top, bool* selection);
 
 #endif

source/game/round.c

@@ -869,13 +869,7 @@ static inline void select_flush_and_straight_cards_in_played_hand(void)
         get_hand_type() == ROYAL_FLUSH)
     {
         bool straight_selection[MAX_HAND_SIZE] = {false};
-        find_straight_in_played_cards(
-            played,
-            played_top,
-            is_shortcut_joker_active(),
-            min_len,
-            straight_selection
-        );
+        find_straight_in_played_cards(played, played_top, min_len, straight_selection);
         // Add the results into the final selection
         for (int i = 0; i <= played_top; i++)
         {

source/hand.c

@@ -583,14 +583,8 @@ int find_flush_in_played_cards(CardObject** played, int top, int min_len, bool*
 }
 
 // Returns the number of cards in the best straight or 0 if no straight of min_len is found, marks
-// as true them in out_selection[]. This is mostly from Google Gemini
-int find_straight_in_played_cards(
-    CardObject** played,
-    int top,
-    bool shortcut_active,
-    int min_len,
-    bool* out_selection
-)
+// them as true in out_selection[]. This is mostly from Google Gemini
+int find_straight_in_played_cards(CardObject** played, int top, int min_len, bool* out_selection)
 {
     if (top < 0)
         return 0;
@@ -617,6 +611,7 @@ int find_straight_in_played_cards(
     // TODO: Consolidate functions to avoid code duplication?
     // Might cost performance because this does a little more
     int ace_low_len = ranks[ACE] ? 1 : 0;
+    bool is_shortcut_active = is_shortcut_joker_active();
     for (int i = 0; i < NUM_RANKS; i++)
     {
         if (ranks[i] > 0)
@@ -624,7 +619,7 @@ int find_straight_in_played_cards(
             int prev1 = 0, prev2 = 0;
             int parent1 = -1, parent2 = -1;
 
-            if (shortcut_active)
+            if (is_shortcut_active)
             {
                 if (i == TWO)
                 {
@@ -733,8 +728,6 @@ int find_straight_in_played_cards(
     return 0;
 }
 
-// This is used for the special case in "Four Fingers" where you can add a pair into a straight
-// (e.g. AA234 should score all 5 cards)
 void select_paired_cards_in_hand(CardObject** played, int played_top, bool* selection)
 {
     // Build a set of ranks that are already selected