doc: update docstrings

Author: yanliutafewa

projects/API Based Weather Report/API Based Weather Report.py

@@ -3,8 +3,17 @@
 from Util_Functions import wind_degree_to_direction, unix_timestamp_to_localtime, convert_temperature
 
 
-# Function to fetch weather data from OpenWeatherMap API
 def fetch_weather(api_key, location):
+    """
+    Function to fetch weather data from OpenWeatherMap API.
+
+    Parameters:
+    api_key (str): API key.
+    location (str): City name.
+
+    Returns:
+    str: The JSON response string.
+    """
     try:
         # Constructing the API link with the provided API key and location
         complete_api_link = f"https://api.openweathermap.org/data/2.5/weather?q={location}&appid={api_key}"
@@ -24,8 +33,15 @@ def fetch_weather(api_key, location):
         return None
 
 
-# Function to write weather information to a text file
 def write_to_file(weather_data, temperature_unit):
+    """
+    Function to write weather information to a text file.
+
+    Parameters:
+    weather_data (str): The JSON API response string.
+    temperature_unit (str): 'C' for Celsius, 'F' for Fahrenheit.
+    """
+
     try:
         # Opening the file "weatherinfo.txt" in write mode
         with open("weatherinfo.txt", "w+") as f:
@@ -97,16 +113,18 @@ def write_to_file(weather_data, temperature_unit):
         print("Error writing to file:", e)
 
 
-# Main function
 def main():
+    """
+    Main function.
+    """
     # Printing welcome messages and instructions
     print("Welcome to the Weather Information App!")
     print("You need an API key to access weather data from OpenWeatherMap.")
     print(
         "You can obtain your API key by signing up at https://home.openweathermap.org/users/sign_up"
     )
 
-    # Prompting the user to input API key, city name, and
+    # Prompting the user to input API key, city name, and temperature unit
     api_key = input("Please enter your OpenWeatherMap API key: ")
     location = input("Enter the city name: ")
     temperature_unit = input("Enter the temperature unit. 'C' for Celsius and 'F' for Fahrenheit: ")
@@ -120,10 +138,12 @@ def main():
 
     # Checking if weather data was successfully fetched
     if weather_data:
+        # Checking if the API key is invalid
         if weather_data["cod"] == "401":
             print("Invalid API key.")
             return
 
+        # Checking if the city is not found
         if weather_data["cod"] == "404":
             print("City not found.")
             return

projects/API Based Weather Report/Util_Functions.py

@@ -5,8 +5,12 @@ def wind_degree_to_direction(str_wind_degree):
     """
     Convert wind degree to wind direction.
 
-    :param str_wind_degree: str, Wind degree from API (0 to 360)
-    :return: Wind direction as a string (e.g., N, NE, E, etc.)
+    Parameters:
+    str_wind_degree (str): Wind degree from API (0 to 360)
+
+    Returns:
+    str: Wind direction (e.g., N, NE, E, etc.)
+         Or message "API Wind Degree data format error!"
     """
     # convert wind degree from str to int.
     try:
@@ -26,9 +30,14 @@ def unix_timestamp_to_localtime(str_unix_timestamp, str_timezone_offset_seconds)
     """
     Convert unix timestamp to localtime (for sunrise and sunset).
 
-    :param str_unix_timestamp: str, Unix timestamp (e.g., "1717715516")
-    :param str_timezone_offset_seconds: str, timezone offset in second (e.g., "28800" represents UTC+8)
-    :return: local_time (e.g., "2024-06-07 07:11:56")
+    Parameters:
+    str_unix_timestamp (str): Unix timestamp (e.g., "1717715516")
+    str_timezone_offset_seconds (str): timezone offset in second (e.g., "28800" represents UTC+8)
+
+    Returns:
+    str: local_time (e.g., "2024-06-07 07:11:56")
+         Or message "API sunset/sunrise data format error!"
+         Or message "API timezone data format error!"
     """
     # Convert strings to integers
     try:
@@ -54,9 +63,14 @@ def convert_temperature(str_temperature_kelvin, temperature_unit):
     """
     Convert temperature in Kelvin degree to Celsius degree or Fahrenheit degree based on second parameter .
 
-    :param str_temperature_kelvin: str, temperature in Kelvin degree (e.g., "291.19")
-    :param temperature_unit: str, "C" for Celsius, "F" for Fahrenheit
-    :return: temperature (e.g., "21.07 °C" or "67.12 °F")
+    Parameters:
+    str_temperature_kelvin (str): temperature in Kelvin degree (e.g., "291.19")
+    temperature_unit (str): "C" for Celsius, "F" for Fahrenheit
+
+    Returns:
+    str: temperature (e.g., "21.07 °C" or "67.12 °F")
+         Or message "API temperature data format error!"
+         Or message "Temperature unit must either be 'C' or be 'F'!"
     """
     # Convert strings to integers
     try: