[Unpacking & Mulit-Assignment Concept Exercise]: Updated docstrings for locomotive-engineer

exercises/concept/locomotive-engineer/.meta/exemplar.py

@@ -2,10 +2,13 @@
 
 
 def get_list_of_wagons(*args):
-    """Return a list of wagons.
+    """Return a list of wagons, given an arbitrary amount of wagon numbers.
 
-    :param *args: arbitrary number of wagons.
-    :return: list - list of wagons.
+    Parameters:
+       *args: An arbitrary number of wagon numbers, unpacked.
+
+    Returns:
+        list: A list of wagon numbers, assembled from *args..
     """
 
     return list(args)
@@ -14,9 +17,12 @@ def get_list_of_wagons(*args):
 def fix_list_of_wagons(each_wagons_id, missing_wagons):
     """Fix the list of wagons.
 
-    :param each_wagons_id: list - the list of wagons.
-    :param missing_wagons: list - the list of missing wagons.
-    :return: list - list of wagons.
+    Parameters:
+        each_wagons_id (list[int]): The list of wagons.
+        missing_wagons (list[int]) The list of missing wagons.
+
+    Returns:
+        list[int]: The corrected list of wagons.
     """
 
     first, second, locomotive, *rest = each_wagons_id
@@ -27,9 +33,12 @@ def fix_list_of_wagons(each_wagons_id, missing_wagons):
 def add_missing_stops(route, **kwargs):
     """Add missing stops to route dict.
 
-    :param route: dict - the dict of routing information.
-    :param **kwargs: arbitrary number of stops.
-    :return: dict - updated route dictionary.
+    Parameters:
+        route (dict): The dict of routing information.
+        **kwargs: arbitrary number of stops.
+
+    Returns:
+        dict: The updated route dictionary.
     """
 
     return {**route, "stops": list(kwargs.values())}
@@ -38,9 +47,12 @@ def add_missing_stops(route, **kwargs):
 def extend_route_information(route, more_route_information):
     """Extend route information with more_route_information.
 
-    :param route: dict - the route information.
-    :param more_route_information: dict - extra route information.
-    :return: dict - extended route information.
+    Parameters:
+        route (dict): The route information.
+        more_route_information (dict): The extra route information.
+
+    Returns:
+        dict: The extended route information.
     """
 
     return {**route, **more_route_information}
@@ -49,8 +61,11 @@ def extend_route_information(route, more_route_information):
 def fix_wagon_depot(wagons_rows):
     """Fix the list of rows of wagons.
 
-    :param wagons_rows: list[tuple] - the list of rows of wagons.
-    :return: list[tuple] - list of rows of wagons.
+    Parameters:
+        wagons_rows (list[tuple]) The list of rows of wagons.
+
+    Returns:
+        list[tuple]: the list of rows of wagons.
     """
 
     [*row_one], [*row_two], [*row_three] = zip(*wagons_rows)

exercises/concept/locomotive-engineer/locomotive_engineer.py

@@ -2,48 +2,63 @@
 
 
 def get_list_of_wagons():
-    """Return a list of wagons.
+    """Return a list of wagons, given an arbitrary amount of wagon numbers.
 
-    :param: arbitrary number of wagons.
-    :return: list - list of wagons.
+    Parameters:
+       An arbitrary number of wagon numbers, unpacked.
+
+    Returns:
+        list: A list of wagon numbers.
     """
     pass
 
 
 def fix_list_of_wagons(each_wagons_id, missing_wagons):
     """Fix the list of wagons.
 
-    :param each_wagons_id: list - the list of wagons.
-    :param missing_wagons: list - the list of missing wagons.
-    :return: list - list of wagons.
+    Parameters:
+        each_wagons_id (list[int]): The list of wagons.
+        missing_wagons (list[int]) The list of missing wagons.
+
+    Returns:
+        list[int]: The corrected list of wagons.
     """
     pass
 
 
-def add_missing_stops():
+def add_missing_stops(route):
     """Add missing stops to route dict.
 
-    :param route: dict - the dict of routing information.
-    :param: arbitrary number of stops.
-    :return: dict - updated route dictionary.
+    Parameters:
+        route (dict): The dict of routing information.
+        (dict): arbitrary number of stops.
+
+    Returns:
+        dict: The updated route dictionary.
     """
     pass
 
 
 def extend_route_information(route, more_route_information):
     """Extend route information with more_route_information.
 
-    :param route: dict - the route information.
-    :param more_route_information: dict -  extra route information.
-    :return: dict - extended route information.
+    Parameters:
+        route (dict): The route information.
+        more_route_information (dict): The extra route information.
+
+    Returns:
+        dict: The extended route information.
     """
     pass
 
 
 def fix_wagon_depot(wagons_rows):
     """Fix the list of rows of wagons.
 
-    :param wagons_rows: list[list[tuple]] - the list of rows of wagons.
-    :return: list[list[tuple]] - list of rows of wagons.
+    Parameters:
+        wagons_rows (list[tuple]) The list of rows of wagons.
+
+    Returns:
+        list[tuple]: the list of rows of wagons.
     """
     pass