Docstring Cleanup

exercises/concept/black-jack/.meta/exemplar.py

@@ -9,10 +9,14 @@ def value_of_card(card):
     """Determine the scoring value of a card.
 
     :param card: str - given card.
-    :return: int - value of a given card. 'J', 'Q', 'K' = 10; 'A' = 1; numerical value otherwise.
+    :return: int - 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.
     """
 
-    if card in('JQK'):
+    if card in ('JQK'):
         value = 10
 
     elif card == 'A':
@@ -27,8 +31,12 @@ 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. 'J', 'Q', 'K' = 10; 'A' = 1; numerical value otherwise.
-    :return: higher value card - str. Tuple of both cards if they are of equal value.
+    :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.
+
+    1.  'J', 'Q', or 'K' (otherwise known as "face cards") = 10
+    2.  'A' (ace card) = 1
+    3.  '2' - '10' = numerical value.
     """
 
     card_one_value = value_of_card(card_one)
@@ -49,10 +57,12 @@ def higher_card(card_one, card_two):
 def value_of_ace(card_one, card_two):
     """Calculate the most advantageous value for the ace card.
 
-    :param card_one, card_two: str - card dealt. 'J', 'Q', 'K' = 10
-           'A' = 11 (if already in hand); numerical value otherwise.
+    :param card_one, card_two: str - card dealt. See below for values.
+    :return: int - either 1 or 11 value of the upcoming ace card.
 
-    :return: int - value of the upcoming ace card (either 1 or 11).
+    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.
     """
 
     card_one_value = 11 if card_one == 'A' else value_of_card(card_one)
@@ -66,8 +76,12 @@ 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 - cards dealt. 'J', 'Q', 'K' = 10; 'A' = 11; numerical value otherwise.
-    :return: bool - if the hand is a blackjack (two cards worth 21).
+    :param card_one, card_two: str - card dealt. See below for values.
+    :return: bool - is the hand is a blackjack (two cards worth 21).
+
+    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.
     """
 
     return (card_one == 'A' or card_two == 'A') and (value_of_card(card_one) == 10 or value_of_card(card_two) == 10)
@@ -77,7 +91,7 @@ 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 - if the hand can be split into two pairs (i.e. cards are of the same value).
+    :return: bool - can the hand be split into two pairs? (i.e. cards are of the same value).
     """
 
     return value_of_card(card_one) == value_of_card(card_two)
@@ -87,7 +101,7 @@ 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 - if the hand can be doubled down (i.e. totals 9, 10 or 11 points).
+    :return: bool - can the hand can be doubled down? (i.e. totals 9, 10 or 11 points).
     """
 
     return 8 < value_of_card(card_one) + value_of_card(card_two) < 12

exercises/concept/black-jack/black_jack.py

@@ -9,7 +9,11 @@ def value_of_card(card):
     """Determine the scoring value of a card.
 
     :param card: str - given card.
-    :return: int - value of a given card. 'J', 'Q', 'K' = 10; 'A' = 1; numerical value otherwise.
+    :return: int - 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
@@ -18,8 +22,12 @@ 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. 'J', 'Q', 'K' = 10; 'A' = 1; numerical value otherwise.
-    :return: higher value card - str. Tuple of both cards if they are of equal value.
+    :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.
+
+    1.  'J', 'Q', or 'K' (otherwise known as "face cards") = 10
+    2.  'A' (ace card) = 1
+    3.  '2' - '10' = numerical value.
     """
 
     pass
@@ -28,10 +36,12 @@ def higher_card(card_one, card_two):
 def value_of_ace(card_one, card_two):
     """Calculate the most advantageous value for the ace card.
 
-    :param card_one, card_two: str - card dealt. 'J', 'Q', 'K' = 10;
-           'A' = 11 (if already in hand); numerical value otherwise.
+    :param card_one, card_two: str - card dealt. See below for values.
+    :return: int - either 1 or 11 value of the upcoming ace card.
 
-    :return: int - value of the upcoming ace card (either 1 or 11).
+    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.
     """
 
     pass
@@ -40,8 +50,12 @@ 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 - cards dealt. 'J', 'Q', 'K' = 10; 'A' = 11; numerical value otherwise.
-    :return: bool - if the hand is a blackjack (two cards worth 21).
+    :param card_one, card_two: str - card dealt. See below for values.
+    :return: bool - is the hand is a blackjack (two cards worth 21).
+
+    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.
     """
 
     pass
@@ -51,7 +65,7 @@ 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 - if the hand can be split into two pairs (i.e. cards are of the same value).
+    :return: bool - can the hand be split into two pairs? (i.e. cards are of the same value).
     """
 
     pass
@@ -61,7 +75,7 @@ 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 - if the hand can be doubled down (i.e. totals 9, 10 or 11 points).
+    :return: bool - can the hand can be doubled down? (i.e. totals 9, 10 or 11 points).
     """
 
     pass

exercises/concept/card-games/.meta/exemplar.py

@@ -30,17 +30,17 @@ def list_contains_round(rounds, number):
 
     :param rounds: list - rounds played.
     :param number: int - round number.
-    :return:  bool - was the round played?
+    :return: bool - was the round played?
     """
 
     return number in rounds
 
 
 def card_average(hand):
-    """Calculate and return the average card value from the list.
+    """Calculate and returns the average card value from the list.
 
     :param hand: list - cards in hand.
-    :return:  float - average value of the cards in the hand.
+    :return: float - average value of the cards in the hand.
     """
 
     return sum(hand) / len(hand)
@@ -50,16 +50,18 @@ def approx_average_is_average(hand):
     """Return if an average is using (first + last index values ) OR ('middle' card) == calculated average.
 
     :param hand: list - cards in hand.
-    :return: bool - if approximate average equals to the `true average`.
+    :return: bool - does one of the approximate averages equal the `true average`?
     """
 
     real_average = card_average(hand)
+
     if card_average([hand[0], hand[-1]]) == real_average:
         is_same = True
     elif hand[len(hand) // 2] == real_average:
         is_same = True
     else:
         is_same = False
+
     return is_same
 
 
@@ -82,4 +84,5 @@ def maybe_double_last(hand):
 
     if hand[-1] == 11:
         hand[-1] *= 2
+
     return hand

exercises/concept/card-games/lists.py

@@ -30,7 +30,7 @@ def list_contains_round(rounds, number):
 
     :param rounds: list - rounds played.
     :param number: int - round number.
-    :return:  bool - was the round played?
+    :return: bool - was the round played?
     """
 
     pass
@@ -40,7 +40,7 @@ def card_average(hand):
     """Calculate and returns the average card value from the list.
 
     :param hand: list - cards in hand.
-    :return:  float - average value of the cards in the hand.
+    :return: float - average value of the cards in the hand.
     """
 
     pass
@@ -50,7 +50,7 @@ def approx_average_is_average(hand):
     """Return if an average is using (first + last index values ) OR ('middle' card) == calculated average.
 
     :param hand: list - cards in hand.
-    :return: bool - if approximate average equals to the `true average`.
+    :return: bool - does one of the approximate averages equal the `true average`?
     """
 
     pass

exercises/concept/cater-waiter/.meta/exemplar.py

@@ -1,3 +1,6 @@
+"""Functions for compiling dishes and ingredients for a catering company."""
+
+
 from sets_categories_data import (VEGAN,
                                   VEGETARIAN,
                                   KETO,
@@ -8,11 +11,11 @@
 
 
 def clean_ingredients(dish_name, dish_ingredients):
-    """
+    """Remove duplicates from `dish_ingredients`.
 
-    :param dish_name: str
-    :param dish_ingredients: list
-    :return: tuple of (dish_name, ingredient set)
+    :param dish_name: str - containing the dish name.
+    :param dish_ingredients: list - dish ingredients.
+    :return: tuple - containing (dish_name, ingredient set).
 
     This function should return a `tuple` with the name of the dish as the first item,
     followed by the de-duped `set` of ingredients as the second item.
@@ -22,14 +25,14 @@ def clean_ingredients(dish_name, dish_ingredients):
 
 
 def check_drinks(drink_name, drink_ingredients):
-    """
+    """Append "Cocktail" (alcohol)  or "Mocktail" (no alcohol) to `drink_name`, based on `drink_ingredients`.
 
-    :param drink_name: str
-    :param drink_ingredients: list
-    :return: str drink name + ("Mocktail" or "Cocktail")
+    :param drink_name: str - name of the drink.
+    :param drink_ingredients: list - ingredients in the drink.
+    :return: str - drink_name appended with "Mocktail" or "Cocktail".
 
-    The function should return the name of the drink followed by "Mocktail" if the drink has
-    no alcoholic ingredients, and drink name followed by "Cocktail" if the drink includes alcohol.
+    The function should return the name of the drink followed by "Mocktail" (non-alcoholic) and drink
+    name followed by "Cocktail" (includes alcohol).
     """
 
     if not ALCOHOLS.isdisjoint(drink_ingredients):
@@ -39,15 +42,16 @@ def check_drinks(drink_name, drink_ingredients):
 
 
 def categorize_dish(dish_name, dish_ingredients):
-    """
+    """Categorize `dish_name` based on `dish_ingredients`.
 
-    :param dish_name: str
-    :param dish_ingredients: list
-    :return: str "dish name: CATEGORY"
+    :param dish_name: str - dish to be categorized.
+    :param dish_ingredients: list - ingredients for the dish.
+    :return: str - the dish name appended with ": <CATEGORY>".
 
     This function should return a string with the `dish name: <CATEGORY>` (which meal category the dish belongs to).
-    All dishes will "fit" into one of the categories imported from `sets_categories_data`
-    (VEGAN, VEGETARIAN, PALEO, KETO, or OMNIVORE).
+    `<CATEGORY>` can be any one of  (VEGAN, VEGETARIAN, PALEO, KETO, or OMNIVORE).
+    All dishes will "fit" into one of the categories imported from `sets_categories_data.py`
+
     """
 
     categories = ((VEGAN, 'VEGAN'),
@@ -63,24 +67,24 @@ def categorize_dish(dish_name, dish_ingredients):
 
 
 def tag_special_ingredients(dish):
-    """
+    """Compare `dish` ingredients to `SPECIAL_INGREDIENTS`.
 
-    :param dish: tuple of (str of dish name, list of dish ingredients)
-    :return: tuple of (str of dish name, set of dish special ingredients)
+    :param dish: tuple - of (dish name, list of dish ingredients).
+    :return: tuple - containing (dish name, dish special ingredients).
 
     Return the dish name followed by the `set` of ingredients that require a special note on the dish description.
     For the purposes of this exercise, all allergens or special ingredients that need to be tracked are in the
-    SPECIAL_INGREDIENTS constant imported from `sets_categories_data`.
+    SPECIAL_INGREDIENTS constant imported from `sets_categories_data.py`.
     """
 
     return dish[0], (SPECIAL_INGREDIENTS & set(dish[1]))
 
 
 def compile_ingredients(dishes):
-    """
+    """Create a master list of ingredients.
 
-    :param dishes: list of dish ingredient sets
-    :return: set
+    :param dishes: list - of dish ingredient sets.
+    :return: set - of ingredients compiled from `dishes`.
 
     This function should return a `set` of all ingredients from all listed dishes.
     """
@@ -94,11 +98,11 @@ def compile_ingredients(dishes):
 
 
 def separate_appetizers(dishes, appetizers):
-    """
+    """Determine which `dishes` are designated `appetizers` and remove them.
 
-    :param dishes: list of dish names
-    :param appetizers: list of appetizer names
-    :return: list of dish names
+    :param dishes: list - of dish names.
+    :param appetizers: list - of appetizer names.
+    :return: list - of dish names that do not appear on appetizer list.
 
     The function should return the list of dish names with appetizer names removed.
     Either list could contain duplicates and may require de-duping.
@@ -108,15 +112,17 @@ def separate_appetizers(dishes, appetizers):
 
 
 def singleton_ingredients(dishes, intersection):
-    """
+    """Determine which `dishes` have a singleton ingredient (an ingredient that only appears once across dishes).
 
-    :param intersection: constant - one of (VEGAN_INTERSECTION,VEGETARIAN_INTERSECTION,PALEO_INTERSECTION,
-                                            KETO_INTERSECTION,OMNIVORE_INTERSECTION)
-    :param dishes:  list of ingredient sets
-    :return: set of singleton ingredients
+    :param dishes: list - of ingredient sets.
+    :param intersection: constant - can be one of `<CATEGORY>_INTERSECTION` constants imported from `sets_categories_data.py`.
+    :return: set - containing singleton ingredients.
 
     Each dish is represented by a `set` of its ingredients.
-    Each `<CATEGORY>_INTERSECTION` is an `intersection` of all dishes in the category.
+
+    Each `<CATEGORY>_INTERSECTION` is an `intersection` of all dishes in the category. `<CATEGORY>` can be any one of:
+        (VEGAN, VEGETARIAN, PALEO, KETO, or OMNIVORE).
+
     The function should return a `set` of ingredients that only appear in a single dish.
     """