Updated docstrings to use Google style. (exercism#4163)

Author: BethanyG

exercises/concept/currency-exchange/.meta/exemplar.py

@@ -6,72 +6,157 @@
 """
 
 def exchange_money(budget, exchange_rate):
-    """
+    """Calculate estimated value after exchange.
+
+    Parameters:
+        budget (float): Tthe amount of money you are planning to exchange.
+        exchange_rate (float): The unit value of the foreign currency.
+
+    Returns:
+        float: The exchanged value of the foreign currency you can receive.
+
+    Examples:
+        >>> exchange_money(127.5, 1.2)
+        106.25
+
+        >>> exchange_money(200, 1.10)
+        181.82
+
+    This function calculates and returns the (estimated) value of the exchanged currency.
 
-    :param budget: float - amount of money you are planning to exchange.
-    :param exchange_rate: float - unit value of the foreign currency.
-    :return: float - exchanged value of the foreign currency you can receive.
     """
 
     return budget / exchange_rate
 
 
 def get_change(budget, exchanging_value):
-    """
+    """Calculate currency left after an exchange.
+
+    Parameters:
+        budget (float): The amount of money you own.
+        exchanging_value (float): The amount of your money you want to exchange now.
+
+    Returns:
+        float: The amount left of your starting currency after the exchange
+
+    Examples:
+        .>>> get_change(127.5, 120.0)
+        7.5
+
+        >>> get_change(300.75, 150.25)
+        150.50
+
+    This function calcultes and returns the amount of money left over from the budget
+    after an exchange.
 
-    :param budget: float - amount of money you own.
-    :param exchanging_value: float - amount of your money you want to exchange now.
-    :return: float - amount left of your starting currency after exchanging.
     """
 
     return budget - exchanging_value
 
 
 def get_value_of_bills(denomination, number_of_bills):
-    """
+    """Calculate the total value of currency at current denomination.
+
+    Parameters:
+        denomination (int): The value of a single unit (bill).
+        number_of_bills (int): The total number of units (bills).
+
+    Returns:
+        int: Calculated value of the units (bills).
+
+    Examples:
+        >>> get_value_of_bills(5, 128)
+        640
+
+        >>> get_value_of_bills(15.13, 16)
+        242
+
+    This function calculates and returns the total value of the bills (excluding fractionaal amounts).
 
-    :param denomination: int - the value of a bill.
-    :param number_of_bills: int - total number of bills.
-    :return: int - calculated value of the bills.
     """
 
     return denomination * number_of_bills
 
 
 def get_number_of_bills(amount, denomination):
-    """
+    """Calculate the number of currency units (bills) within the amount.
+
+    Parameters:
+        amount (float): The total starting value.
+        denomination (int): The value of a single unit (bill).
+
+    Returns:
+        int: The number of units (bills) that can be obtained from the amount.
+
+    Examples:
+        >>> get_number_of_bills(127.5, 5)
+        25
+
+        >>> get_number_of_bills(35.16, 10)
+        3
+
+    This function calcluates and returns the number pf currency units (bills) that can
+    be obtained from the given amount. Whole bills only - no fractioal amounts.
 
-    :param amount: float - the total starting value.
-    :param denomination: int - the value of a single bill.
-    :return: int - number of bills that can be obtained from the amount.
     """
 
     return int(amount) // denomination
 
 
 def get_leftover_of_bills(amount, denomination):
-    """
+    """Calculate leftover amount after exchanging into bills.
+
+    Parameters:
+        amount (float): The total starting value.
+        denomination (int): The value of a single unit (bill).
+
+    Returns:
+        float: The amount that is "leftover", given the current denomination.
+
+    Examples:
+        >>> get_leftover_of_bills(127.5, 20)
+        7.5
+
+        >>> get_leftover_of_bills(153.2, 10)
+        3.20
+
+    This function calculates and returns the leftover amount that cannot be
+    returned from starting amount, due to the currency denomination.
 
-    :param amount: float - the total starting value.
-    :param denomination: int - the value of a single bill.
-    :return: float - the amount that is "leftover", given the current denomination.
     """
 
     return amount % denomination
 
 
 def exchangeable_value(budget, exchange_rate, spread, denomination):
-    """
+    """Calculate the maximum value of the new currency.
+
+    Parameters:
+        budget (float): The amount of your money you are planning to exchange.
+        exchange_rate (float): The unit value of the foreign currency.
+        spread (int): The percentage that is taken as an exchange fee.
+        denomination (int) The value of a single unit (bill).
+
+    Returns:
+        int: The maximum value you can get in the new currency.
 
-    :param budget: float - the amount of your money you are planning to exchange.
-    :param exchange_rate: float - the unit value of the foreign currency.
-    :param spread: int - percentage that is taken as an exchange fee.
-    :param denomination: int - the value of a single bill.
-    :return: int - maximum value you can get.
+    Examples:
+        >>> exchangeable_value(127.25, 1.20, 10, 20)
+        80
+
+        >>> exchangeable_value(127.25, 1.20, 10, 5)
+        95
+
+    Note:
+        The currency denomination is a whole number and cannot be sub-divided.
+
+    This function calculates and returns the maximum value of the new currency after
+    determining the exchange rate plus the spread.
     """
 
     exchange_fee = (exchange_rate / 100) * spread
     exchange_value = exchange_money(budget, exchange_rate + exchange_fee)
     number_of_bills = get_number_of_bills(exchange_value, denomination)
     value_of_bills = get_value_of_bills(denomination, number_of_bills)
+
     return value_of_bills

exercises/concept/currency-exchange/exchange.py

@@ -48,7 +48,7 @@ def get_change(budget, exchanging_value):
         >>> get_change(300.75, 150.25)
         150.50
 
-    Tthis function calcultes and returns the amount of money left over from the budget
+    This function calcultes and returns the amount of money left over from the budget
     after an exchange.
 
     """

exercises/concept/ellens-alien-game/.meta/exemplar.py

@@ -4,34 +4,37 @@
 class Alien:
     """Create an Alien object with location x_coordinate and y_coordinate.
 
-    Attributes
-    ----------
-    (class)total_aliens_created: int
-    x_coordinate: int - Position on the x-axis.
-    y_coordinate: int - Position on the y-axis.
-    health: int - Number of health points.
-
-    Methods
-    -------
-    hit(): Decrement Alien health by one point.
-    is_alive(): Return a boolean to indicate if Alien is alive (if health is > 0).
-    teleport(new_x_coordinate, new_y_coordinate): Move Alien object to new coordinates.
-    collision_detection(other): Implementation TBD.
+    Attributes:
+        (class) total_aliens_created (int): Total number of Alien instances.
+        x_coordinate (int):  Position on the x-axis.
+        y_coordinate (int): Position on the y-axis.
+        health (int):  Number of health points.
+
+    Methods:
+        hit(): Decrement Alien health by one point.
+        is_alive(): Return a boolean for if Alien is alive (if health is > 0).
+        teleport(new_x_coordinate, new_y_coordinate): Move Alien object to new coordinates.
+        collision_detection(other): Implementation TBD.
+
     """
 
     total_aliens_created = 0
 
     def __init__(self, x_coordinate, y_coordinate):
         """Initialize a new Alien object and increment total_aliens_created by 1.
 
-        :param x_coordinate: int - Alien position on the x-axis
-        :param y_coordinate: int - Alien position on the y-axis
+        Parameters:
+            x_coordinate (int):  Position on the x-axis.
+            y_coordinate (int): Position on the y-axis.
+            health (int):  Number of health points.
 
-        :attribute x_coordinate: int - Alien position on the x-axis
-        :attribute y_coordinate: int - Alien position on the y-axis
-        :attribute health: int (3) - Initial Alien health points.
+        Attributes:
+            x_coordinate (int):  Position on the x-axis.
+            y_coordinate (int): Position on the y-axis.
+            health (int):  Number of health points. Defaults to 3.
 
-        :return: object - New Alien.
+        Returns:
+            Alien (Alien Object): New Alien.
         """
 
         Alien.total_aliens_created += 1
@@ -43,7 +46,8 @@ def __init__(self, x_coordinate, y_coordinate):
     def hit(self):
         """Decrement Alien health by 1.
 
-        :return: None
+        Returns:
+            None
         """
 
         #There are two valid interpretations for this method/task.
@@ -54,37 +58,47 @@ def hit(self):
     def is_alive(self):
         """Return if the Alien is alive.
 
-        :return: boolean
+        Returns:
+            bool:  Is the Alien Alive?
         """
 
         return self.health > 0
 
     def teleport(self, new_x_coordinate, new_y_coordinate):
         """Change Alien location.
 
-        :param new_x_coordinate: int - New location on x-axis.
-        :param new_y_coordinate: int - New location on y-axis.
+        Parameters:
+            new_x_coordinate (int): New location on x-axis.
+            new_y_coordinate (int): New location on y-axis.
 
-        :return: None
+        Returns:
+            None
         """
+
         self.x_coordinate = new_x_coordinate
         self.y_coordinate = new_y_coordinate
 
     def collision_detection(self, other):
         """Detect collisions with another Alien.
 
-        :param other: object - Other Alien object.
+        Parameters:
+            other (object): Other Alien object.
 
-        :return: None
+        Returns:
+            None
         """
 
         pass
 
+
 def new_aliens_collection(positions):
     """Create a list of Alien instances from a list of coordinate tuples.
 
-     :param positions: list - List of tuples of (x, y) coordinates.
+     Parameters:
+        positions (list[tuple]): List of (x, y) coordinates in tuples..
 
-     :return: list - List of Alien objects.
+     Returns:
+         list[object]: List of Alien objects.
      """
+
     return [Alien(position[0], position[1]) for position in positions]

exercises/concept/ghost-gobble-arcade-game/.meta/exemplar.py

@@ -4,9 +4,13 @@
 def eat_ghost(power_pellet_active, touching_ghost):
     """Verify that Pac-Man can eat a ghost if he is empowered by a power pellet.
 
-    :param power_pellet_active: bool - does the player have an active power pellet?
-    :param touching_ghost: bool - is the player touching a ghost?
-    :return: bool - can a ghost be eaten?
+    Parameters:
+        power_pellet_active (bool): Does the player have an active power pellet?
+        touching_ghost (bool): Is the player touching a ghost?
+
+    Returns:
+        bool: Can a ghost be eaten?
+
     """
 
     return power_pellet_active and touching_ghost
@@ -15,9 +19,13 @@ def eat_ghost(power_pellet_active, touching_ghost):
 def score(touching_power_pellet, touching_dot):
     """Verify that Pac-Man has scored when a power pellet or dot has been eaten.
 
-    :param touching_power_pellet: bool - is the player touching a power pellet?
-    :param touching_dot: bool - is the player touching a dot?
-    :return: bool - has the player scored or not?
+    Parameters:
+        touching_power_pellet (bool): Is the player touching a power pellet?
+        touching_dot (bool): Is the player touching a dot?
+
+    Returns:
+        bool: Has the player scored or not?
+
     """
 
     return touching_power_pellet or touching_dot
@@ -26,9 +34,12 @@ def score(touching_power_pellet, touching_dot):
 def lose(power_pellet_active, touching_ghost):
     """Trigger the game loop to end (GAME OVER) when Pac-Man touches a ghost without his power pellet.
 
-    :param power_pellet_active: bool - does the player have an active power pellet?
-    :param touching_ghost: bool - is the player touching a ghost?
-    :return: bool - has the player lost the game?
+    Parameters:
+        power_pellet_active (bool): Does the player have an active power pellet?
+        touching_ghost (bool): Is the player touching a ghost?
+
+    Returns:
+        bool: Has the player lost the game?
     """
 
     return not power_pellet_active and touching_ghost
@@ -37,10 +48,13 @@ def lose(power_pellet_active, touching_ghost):
 def win(has_eaten_all_dots, power_pellet_active, touching_ghost):
     """Trigger the victory event when all dots have been eaten.
 
-    :param has_eaten_all_dots: bool - has the player "eaten" all the dots?
-    :param power_pellet_active: bool - does the player have an active power pellet?
-    :param touching_ghost: bool - is the player touching a ghost?
-    :return: bool - has the player won the game?
+    Parameters:
+        has_eaten_all_dots (bool): Has the player "eaten" all the dots?
+        power_pellet_active (bool): Does the player have an active power pellet?
+        touching_ghost (bool): Is the player touching a ghost?
+
+    Returns:
+        bool: Has the player won the game?
     """
 
     return has_eaten_all_dots and not lose(power_pellet_active, touching_ghost)