[Comparisons Concept Exercise ]: Updated docstrings in stub for black-jack

exercises/concept/black-jack/black_jack.py

@@ -8,12 +8,15 @@
 def value_of_card(card):
     """Determine the scoring value of a card.
 
-    :param card: str - given card.
-    :return: int - value of a given card.  See below for values.
+    Parameters:
+        card (str): The given card.
 
-    1.  'J', 'Q', or 'K' (otherwise known as "face cards") = 10
-    2.  'A' (ace card) = 1
-    3.  '2' - '10' = numerical value.
+    Returns:
+        int:  The value of a given card.  See below for values.
+
+        1.  'J', 'Q', or 'K' (otherwise known as "face cards") = 10
+        2.  'A' (ace card) = 1
+        3.  '2' - '10' = numerical value.
     """
 
     pass
@@ -22,12 +25,16 @@ def value_of_card(card):
 def higher_card(card_one, card_two):
     """Determine which card has a higher value in the hand.
 
-    :param card_one, card_two: str - cards dealt in hand.  See below for values.
-    :return: str or tuple - resulting Tuple contains both cards if they are of equal value.
+    Parameters:
+        card_one (str): First card dealt in the hand.  See below for values.
+        card_two (str): Second card dealt in the hand. See below for values.
+
+        1.  'J', 'Q', or 'K' (otherwise known as "face cards") = 10
+        2.  'A' (ace card) = 1
+        3.  '2' - '10' = numerical value.
 
-    1.  'J', 'Q', or 'K' (otherwise known as "face cards") = 10
-    2.  'A' (ace card) = 1
-    3.  '2' - '10' = numerical value.
+    Returns:
+        str or tuple: The resulting Tuple contains both cards if they are of equal value.
     """
 
     pass
@@ -36,12 +43,16 @@ def higher_card(card_one, card_two):
 def value_of_ace(card_one, card_two):
     """Calculate the most advantageous value for an upcoming ace card.
 
-    :param card_one, card_two: str - card dealt. See below for values.
-    :return: int - either 1 or 11 value of the upcoming ace card.
+    Parameters:
+        card_one (str): First card dealt in the hand.  See below for values.
+        card_two (str): Second card dealt in the hand. See below for values.
+
+        1.  'J', 'Q', or 'K' (otherwise known as "face cards") = 10
+        2.  'A' (ace card) = 11 (if already in hand)
+        3.  '2' - '10' = numerical value.
 
-    1.  'J', 'Q', or 'K' (otherwise known as "face cards") = 10
-    2.  'A' (ace card) = 11 (if already in hand)
-    3.  '2' - '10' = numerical value.
+    Returns:
+        int: Either 1 or 11, which is the value of the upcoming ace card.
     """
 
     pass
@@ -50,12 +61,16 @@ def value_of_ace(card_one, card_two):
 def is_blackjack(card_one, card_two):
     """Determine if the hand is a 'natural' or 'blackjack'.
 
-    :param card_one, card_two: str - card dealt. See below for values.
-    :return: bool - is the hand is a blackjack (two cards worth 21).
+    Parameters:
+        card_one (str): First card dealt in the hand.  See below for values.
+        card_two (str): Second card dealt in the hand. See below for values.
 
-    1.  'J', 'Q', or 'K' (otherwise known as "face cards") = 10
-    2.  'A' (ace card) = 11 (if already in hand)
-    3.  '2' - '10' = numerical value.
+        1.  'J', 'Q', or 'K' (otherwise known as "face cards") = 10
+        2.  'A' (ace card) = 11 (if already in hand)
+        3.  '2' - '10' = numerical value.
+
+    Returns:
+        bool: Is the hand is a blackjack (two cards worth 21).
     """
 
     pass
@@ -64,8 +79,12 @@ def is_blackjack(card_one, card_two):
 def can_split_pairs(card_one, card_two):
     """Determine if a player can split their hand into two hands.
 
-    :param card_one, card_two: str - cards dealt.
-    :return: bool - can the hand be split into two pairs? (i.e. cards are of the same value).
+    Parameters:
+        card_one (str): First card in the hand.
+        card_two (str): Second card in the hand.
+
+   Returns:
+        bool: Can the hand be split into two pairs? (i.e. cards are of the same value).
     """
 
     pass
@@ -74,8 +93,12 @@ def can_split_pairs(card_one, card_two):
 def can_double_down(card_one, card_two):
     """Determine if a blackjack player can place a double down bet.
 
-    :param card_one, card_two: str - first and second cards in hand.
-    :return: bool - can the hand can be doubled down? (i.e. totals 9, 10 or 11 points).
+    Parameters:
+        card_one (str): First card in the hand.
+        card_two (str): Second card in the hand.
+
+    Returns:
+        bool: Can the hand can be doubled down? (i.e. totals 9, 10 or 11 points).
     """
 
     pass