Add docstring to plot_plan.

common.py

@@ -1,23 +1,55 @@
-from typing import List, Tuple
+from typing import Dict, List, Tuple
+
+import matplotlib.pyplot as plt
 import numpy as np
 import numpy.typing as npt
-import matplotlib.pyplot as plt
 
 # Data given by the assignment
-city_coords = {
+city_coords: Dict = {
-    "Barcelona": [2.154007, 41.390205], "Belgrade": [20.46, 44.79], "Berlin": [13.40, 52.52], 
+    "Barcelona": [2.154007, 41.390205],
-    "Brussels": [4.35, 50.85], "Bucharest": [26.10, 44.44], "Budapest": [19.04, 47.50],
+    "Belgrade": [20.46, 44.79],
-    "Copenhagen": [12.57, 55.68], "Dublin": [-6.27, 53.35], "Hamburg": [9.99, 53.55], 
+    "Berlin": [13.40, 52.52],
-    "Istanbul": [28.98, 41.02], "Kyiv": [30.52, 50.45], "London": [-0.12, 51.51], 
+    "Brussels": [4.35, 50.85],
-    "Madrid": [-3.70, 40.42], "Milan": [9.19, 45.46], "Moscow": [37.62, 55.75],
+    "Bucharest": [26.10, 44.44],
-    "Munich": [11.58, 48.14], "Paris": [2.35, 48.86], "Prague": [14.42, 50.07],
+    "Budapest": [19.04, 47.50],
-    "Rome": [12.50, 41.90], "Saint Petersburg": [30.31, 59.94], "Sofia": [23.32, 42.70],
+    "Copenhagen": [12.57, 55.68],
-    "Stockholm": [18.06, 60.33], "Vienna": [16.36, 48.21], "Warsaw": [21.02, 52.24]}
+    "Dublin": [-6.27, 53.35],
+    "Hamburg": [9.99, 53.55],
+    "Istanbul": [28.98, 41.02],
+    "Kyiv": [30.52, 50.45],
+    "London": [-0.12, 51.51],
+    "Madrid": [-3.70, 40.42],
+    "Milan": [9.19, 45.46],
+    "Moscow": [37.62, 55.75],
+    "Munich": [11.58, 48.14],
+    "Paris": [2.35, 48.86],
+    "Prague": [14.42, 50.07],
+    "Rome": [12.50, 41.90],
+    "Saint Petersburg": [30.31, 59.94],
+    "Sofia": [23.32, 42.70],
+    "Stockholm": [18.06, 60.33],
+    "Vienna": [16.36, 48.21],
+    "Warsaw": [21.02, 52.24],
+}
+
 
 def plot_plan(city_order: List[str]) -> None:
-    europe_map = plt.imread('map.png')
+    """A function that plots the circuit given by city_order.
-    fig, ax = plt.subplots(figsize=(10, 10))
+
-    ax.imshow(europe_map, extent=[-14.56, 38.43, 37.697 + 0.3, 64.344 + 2.0], aspect="auto")
+    This function was given in the assignment from 2024.
+
+    Args:
+        city_order (List[str]): A list of cities in the order to be plotted.
+
+    Returns: 
+        None
+    """
+
+    europe_map = plt.imread("map.png")
+    _, ax = plt.subplots(figsize=(10, 10))
+    ax.imshow(
+        europe_map, extent=[-14.56, 38.43, 37.697 + 0.3, 64.344 + 2.0], aspect="auto"
+    )
 
     # Map (long, lat) to (x, y) for plotting
     for index in range(len(city_order) - 1):
@@ -28,17 +60,18 @@ def plot_plan(city_order: List[str]) -> None:
         next_x, next_y = next_city_coords[0], next_city_coords[1]
         plt.plot([x, next_x], [y, next_y])
 
-        plt.plot(x, y, 'ok', markersize=5)
+        plt.plot(x, y, "ok", markersize=5)
         plt.text(x, y, str(index), fontsize=12)
     # Finally, plotting from last to first city
     first_city_coords = city_coords[city_order[0]]
     first_x, first_y = first_city_coords[0], first_city_coords[1]
     plt.plot([next_x, first_x], [next_y, first_y])
     # Plotting a marker and index for the final city
-    plt.plot(next_x, next_y, 'ok', markersize=5)
+    plt.plot(next_x, next_y, "ok", markersize=5)
     plt.text(next_x, next_y, str(index + 1), fontsize=12)
     plt.show()
 
+
 def read_data(file_path: str) -> Tuple[npt.NDArray, npt.NDArray]:
     """Read the city data from a file given and return 2 arrays.
 
@@ -55,6 +88,7 @@ def read_data(file_path: str) -> Tuple[npt.NDArray, npt.NDArray]:
         and the data associated with it.
 
     """
+
     cities = None
     data = []
     with open(file_path, "r") as f:
@@ -67,6 +101,7 @@ def read_data(file_path: str) -> Tuple[npt.NDArray, npt.NDArray]:
 
 
 if __name__ == "__main__":
+    # A test program to see that the file is read correctly.
     cities, data = read_data("./european_cities.csv")
     print(cities)
     print(data)