Updated docstrings in exemplar files to use Google style. (exercism#4164)

Author: BethanyG

exercises/concept/black-jack/.meta/exemplar.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.
     """
 
     if card in ('JQK'):
@@ -31,12 +34,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.
     """
 
     card_one_value = value_of_card(card_one)
@@ -55,14 +62,18 @@ def higher_card(card_one, card_two):
 
 
 def value_of_ace(card_one, card_two):
-    """Calculate the most advantageous value for the ace card.
+    """Calculate the most advantageous value for an 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.
 
-    :param card_one, card_two: str - card dealt. See below for values.
-    :return: int - either 1 or 11 value of the upcoming ace card.
+        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.
     """
 
     card_one_value = 11 if card_one == 'A' else value_of_card(card_one)
@@ -76,12 +87,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).
     """
 
     return (card_one == 'A' or card_two == 'A') and (value_of_card(card_one) == 10 or value_of_card(card_two) == 10)
@@ -90,8 +105,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).
     """
 
     return value_of_card(card_one) == value_of_card(card_two)
@@ -100,8 +119,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).
     """
 
     return 8 < value_of_card(card_one) + value_of_card(card_two) < 12

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

@@ -7,8 +7,11 @@
 def get_rounds(number):
     """Create a list containing the current and next two round numbers.
 
-    :param number: int - current round number.
-    :return: list - current round and the two that follow.
+    Parameters:
+        number (int):  The current round number.
+
+    Returns:
+        list: The current round number and the two that follow.
     """
 
     return [number, number + 1, number + 2]
@@ -17,9 +20,12 @@ def get_rounds(number):
 def concatenate_rounds(rounds_1, rounds_2):
     """Concatenate two lists of round numbers.
 
-    :param rounds_1: list - first rounds played.
-    :param rounds_2: list - second set of rounds played.
-    :return: list - all rounds played.
+    Parameters:
+        rounds_1 (list):  The first rounds played.
+        rounds_2 (list): The second group of rounds played.
+
+    Returns:
+        list:  All rounds played.
     """
 
     return rounds_1 + rounds_2
@@ -28,9 +34,12 @@ def concatenate_rounds(rounds_1, rounds_2):
 def list_contains_round(rounds, number):
     """Check if the list of rounds contains the specified number.
 
-    :param rounds: list - rounds played.
-    :param number: int - round number.
-    :return: bool - was the round played?
+    Parameters:
+        rounds  (list): The rounds played.
+        number (int): The round number.
+
+    Returns:
+        bool: Was the round played?
     """
 
     return number in rounds
@@ -39,8 +48,11 @@ def list_contains_round(rounds, number):
 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.
+    Parameters:
+        hand (list): The cards in the hand.
+
+    Returns:
+        float: The average value of the cards in the hand.
     """
 
     return sum(hand) / len(hand)
@@ -49,8 +61,11 @@ def card_average(hand):
 def approx_average_is_average(hand):
     """Return if the (average of first and last card values) OR ('middle' card) == calculated average.
 
-    :param hand: list - cards in hand.
-    :return: bool - does one of the approximate averages equal the `true average`?
+    Parameters:
+        hand (list): The cards in the hand.
+
+    Returns:
+        bool: Does one of the approximate averages equal the `true average`?
     """
 
     real_average = card_average(hand)
@@ -68,8 +83,11 @@ def approx_average_is_average(hand):
 def average_even_is_average_odd(hand):
     """Return if the (average of even indexed card values) == (average of odd indexed card values).
 
-    :param hand: list - cards in hand.
-    :return: bool - are even and odd averages equal?
+    Parameters:
+        hand (list): The cards in the hand.
+
+    Returns:
+        bool: Are the even and odd averages equal?
     """
 
     return card_average(hand[::2]) == card_average(hand[1::2])
@@ -78,8 +96,11 @@ def average_even_is_average_odd(hand):
 def maybe_double_last(hand):
     """Multiply a Jack card value in the last index position by 2.
 
-    :param hand: list - cards in hand.
-    :return: list - hand with Jacks (if present) value doubled.
+    Parameters:
+        hand (list): The cards in the hand.
+
+    Returns:
+        list: The hand with Jacks (if present) value doubled.
     """
 
     if hand[-1] == 11:

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

@@ -13,12 +13,16 @@
 def clean_ingredients(dish_name, dish_ingredients):
     """Remove duplicates from `dish_ingredients`.
 
-    :param dish_name: str - containing the dish name.
-    :param dish_ingredients: list - dish ingredients.
-    :return: tuple - containing (dish_name, ingredient set).
+    Parameters:
+        dish_name (str):  The name of the dish.
+        dish_ingredients (list): The ingredients for the dish.
+
+    Returns:
+        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.
+
     """
 
     return dish_name, set(dish_ingredients)
@@ -27,12 +31,16 @@ 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 - name of the drink.
-    :param drink_ingredients: list - ingredients in the drink.
-    :return: str - drink_name appended with "Mocktail" or "Cocktail".
+    Parameters:
+        drink_name (str): Name of the drink.
+        drink_ingredients (list): Ingredients in the drink.
+
+    Returns:
+        str: drink_name appended with "Mocktail" or "Cocktail".
 
     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):
@@ -44,13 +52,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 - dish to be categorized.
-    :param dish_ingredients: list - ingredients for the dish.
-    :return: str - the dish name appended with ": <CATEGORY>".
+    Parameters:
+        dish_name (str): The dish to be categorized.
+        dish_ingredients (set): The ingredients for the dish.
+
+    Returns:
+        str: TThe dish name appended with ": <CATEGORY>".
 
     This function should return a string with the `dish name: <CATEGORY>` (which meal category the dish belongs to).
     `<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`
+    All dishes will "fit" into one of the categories imported from `sets_categories_data.py`.
 
     """
 
@@ -69,8 +80,11 @@ def categorize_dish(dish_name, dish_ingredients):
 def tag_special_ingredients(dish):
     """Compare `dish` ingredients to `SPECIAL_INGREDIENTS`.
 
-    :param dish: tuple - of (dish name, list of dish ingredients).
-    :return: tuple - containing (dish name, dish special ingredients).
+    Parameters:
+        dish (tuple): (dish name, list of dish ingredients).
+
+    Returns:
+        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
@@ -81,12 +95,17 @@ def tag_special_ingredients(dish):
 
 
 def compile_ingredients(dishes):
-    """Create a master list of ingredients.
+    """Determine which `dishes` are designated `appetizers` and remove them.
+
+    Parameters:
+        dishes (list): Group of dish names.
+        appetizers (list): Group of appetizer names.
 
-    :param dishes: list - of dish ingredient sets.
-    :return: set - of ingredients compiled from `dishes`.
+    Returns:
+        list: Group of dish names that do not appear on appetizer list.
 
-    This function should return a `set` of all ingredients from all listed dishes.
+    The function should return the list of dish names with appetizer names removed.
+    Either list could contain duplicates and may require de-duping.
     """
 
     combined_ingredients = set()
@@ -100,9 +119,12 @@ 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 that do not appear on appetizer list.
+    Parameters:
+        dishes (list): Group of dish names.
+        appetizers (list): Group of appetizer names.
+
+    Returns:
+        list: Group 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.
@@ -114,13 +136,16 @@ 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 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.
+    Parameters:
+        dishes (list): Group of ingredient sets.
+        intersection (constant): Can be one of `<CATEGORY>_INTERSECTIONS` constants imported from `sets_categories_data.py`.
+
+    Returns:
+        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. `<CATEGORY>` can be any one of:
+    Each `<CATEGORY>_INTERSECTIONS` 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.