From decbd83316b316c15e36adfda9b104d86f9bd0ac Mon Sep 17 00:00:00 2001 From: Martin Eyben Date: Tue, 19 Nov 2024 17:59:45 +0100 Subject: [PATCH] feat: documentation --- src/main/java/eirb/pg203/City.java | 8 +++ src/main/java/eirb/pg203/Main.java | 19 +++++- src/main/java/eirb/pg203/OpenMeteo.java | 9 +++ src/main/java/eirb/pg203/OpenWeatherMap.java | 5 +- src/main/java/eirb/pg203/WeatherData.java | 59 ++++++++++++++++++- src/main/java/eirb/pg203/WeatherDataAPI.java | 2 +- .../exceptions/WeatherFetchingException.java | 7 +++ src/main/java/eirb/pg203/utils/Coords.java | 24 ++++++++ .../java/eirb/pg203/utils/JSONFetcher.java | 27 ++++++++- 9 files changed, 152 insertions(+), 8 deletions(-) diff --git a/src/main/java/eirb/pg203/City.java b/src/main/java/eirb/pg203/City.java index 6a9dbb9..9051b0d 100644 --- a/src/main/java/eirb/pg203/City.java +++ b/src/main/java/eirb/pg203/City.java @@ -13,6 +13,10 @@ import org.json.JSONObject; import eirb.pg203.utils.Coords; +/** + * Representation of a city + * Possibility to get city coordinates based on the name + */ public class City { private String cityName; private Coords cityCoords; @@ -49,6 +53,10 @@ public class City { this.cityName = cityName; } + /** + * Get city name + * @return city name string + */ public String getCityName() { return cityName; } diff --git a/src/main/java/eirb/pg203/Main.java b/src/main/java/eirb/pg203/Main.java index 1ed2048..25b7d95 100644 --- a/src/main/java/eirb/pg203/Main.java +++ b/src/main/java/eirb/pg203/Main.java @@ -1,12 +1,19 @@ package eirb.pg203; -import java.io.IOException; -import java.time.Instant; import java.util.ArrayList; import java.util.HashMap; import java.util.List; +/** + * Main class + */ public class Main { + + /** + * Default constructor (private) + */ + private Main() {}; + private static class Option { String flag, value; public Option(String flag, String value){ @@ -27,7 +34,13 @@ public class Main { return value; } } - public static void main(String[] args) throws IOException, IllegalArgumentException{ + + /** + * Main loop + * @param args list of arguments + * @throws IllegalArgumentException if arguments are not provided or in a wrong way + */ + public static void main(String[] args) throws IllegalArgumentException{ HashMap options = new HashMap<>(); List argsList = new ArrayList<>(); diff --git a/src/main/java/eirb/pg203/OpenMeteo.java b/src/main/java/eirb/pg203/OpenMeteo.java index c33e999..d0ee73b 100644 --- a/src/main/java/eirb/pg203/OpenMeteo.java +++ b/src/main/java/eirb/pg203/OpenMeteo.java @@ -14,10 +14,19 @@ import eirb.pg203.WeatherData.Condition; // https://api.open-meteo.com/v1/forecast?latitude=52.52&longitude=13.41&hourly=temperature_2m +/** + * OpenMeteo implementation + */ public class OpenMeteo implements WeatherDataAPI { private static final String forecastBaseURL = "https://api.open-meteo.com/v1/forecast"; private static final String dailyQuery = "weather_code,temperature_2m_max,temperature_2m_min,wind_speed_10m_max,wind_direction_10m_dominant"; + /** + * Default constructor + */ + public OpenMeteo() {} + + // https://www.nodc.noaa.gov/archive/arc0021/0002199/1.1/data/0-data/HTML/WMO-CODE/WMO4677.HTM private JSONObject fetchWeather(int days, City city) throws IOException { URL url = URI.create( diff --git a/src/main/java/eirb/pg203/OpenWeatherMap.java b/src/main/java/eirb/pg203/OpenWeatherMap.java index 6ea2d91..e811d15 100644 --- a/src/main/java/eirb/pg203/OpenWeatherMap.java +++ b/src/main/java/eirb/pg203/OpenWeatherMap.java @@ -14,8 +14,9 @@ import java.time.ZoneId; import java.util.ArrayList; import eirb.pg203.WeatherData.Condition; -// https://api.open-meteo.com/v1/forecast?latitude=52.52&longitude=13.41&hourly=temperature_2m - +/** + * OpenWeatherMap api implementation + */ public class OpenWeatherMap implements WeatherDataAPI { private static final String forecastBaseURL = "https://api.openweathermap.org/data/2.5/forecast"; private String APIKey; diff --git a/src/main/java/eirb/pg203/WeatherData.java b/src/main/java/eirb/pg203/WeatherData.java index 0b558ed..1006651 100644 --- a/src/main/java/eirb/pg203/WeatherData.java +++ b/src/main/java/eirb/pg203/WeatherData.java @@ -3,16 +3,36 @@ package eirb.pg203; import java.time.Instant; import java.util.concurrent.locks.Condition; +/** + * Weather Data representation + * A weather data is a Temperature, on a date, in a city, with a weather condition and wind speed + direction + * The representation of the data is managed in this class. + */ public class WeatherData { /** * Representation of a weather condition (with a smiley for String representation) */ public enum Condition { + /** + * Sunny condition + */ SUNNY("☀️"), + /** + * A little a bit of sun and a little bit of clouds + */ PARTIAL("🌤"), + /** + * Cloudy weather + */ CLOUDY("☁️"), + /** + * Rainy weather -> like most of the time in Bordeaux + */ RAINY("🌧"), + /** + * Impossible to determine a Weather Condition + */ ERROR("E"); private final String desc; @@ -28,14 +48,42 @@ public class WeatherData { * Representation of the wind direction with an arrow */ public enum WindDirection { + /** + * North direction + */ N("🡩"), + /** + * North East direction + */ NE("🡭"), + /** + * East direction + */ E("🡪"), + /** + * South East direction + */ SE("🡮"), + /** + * South direction + */ S("🡫"), + /** + * South West direction + */ SW("🡯"), + /** + * West direction + */ W("🡨"), + /** + * North West direction + */ NW("🡬"), + + /** + * Error wind direction + */ ERROR("E"); private final String desc; @@ -93,6 +141,7 @@ public class WeatherData { } /** + * Get city from where the weather data come from * @return city */ public City getCity() { @@ -100,7 +149,7 @@ public class WeatherData { } /** - * + * Get date of the weather data * @return date of the Weather data */ public Instant getDate() { @@ -108,6 +157,7 @@ public class WeatherData { } /** + * Get weather condition representation * @return Weather Condition representation */ public Condition getCondition() { @@ -115,6 +165,7 @@ public class WeatherData { } /** + * Get temperature value * @return float temperature */ public float getTemp() { @@ -122,6 +173,7 @@ public class WeatherData { } /** + * Get wind speed value * @return wind speed */ public float getWindSpeed() { @@ -129,11 +181,13 @@ public class WeatherData { } /** + * Get wind direction angle value * @return Wind direction angle */ public float getWindDirectionAngle() {return this.windDirectionAngle;} /** + * Get wind direction representation * @return wind direction representation */ public WindDirection getWindDirection() { @@ -165,6 +219,7 @@ public class WeatherData { } /** + * Set temperature value * @param temp Weather data temperature */ public void setTemp(float temp) { @@ -172,6 +227,7 @@ public class WeatherData { } /** + * Set wind speed value * @param windSpeed Wind speed */ public void setWindSpeed(float windSpeed) { @@ -179,6 +235,7 @@ public class WeatherData { } /** + * Set wind direction angle value * @param windDirectionAngle wind direction angle */ public void setWindDirectionAngle(float windDirectionAngle) { diff --git a/src/main/java/eirb/pg203/WeatherDataAPI.java b/src/main/java/eirb/pg203/WeatherDataAPI.java index ab269f7..c91c416 100644 --- a/src/main/java/eirb/pg203/WeatherDataAPI.java +++ b/src/main/java/eirb/pg203/WeatherDataAPI.java @@ -18,7 +18,7 @@ public interface WeatherDataAPI { WeatherData getTemperature(int day, String city) throws IOException; /** - * + * Get WeatherData for a specific day * @param day Since D+0 * @param hour Since H+0 * @param city Localisation diff --git a/src/main/java/eirb/pg203/exceptions/WeatherFetchingException.java b/src/main/java/eirb/pg203/exceptions/WeatherFetchingException.java index 4e21982..bf286f4 100644 --- a/src/main/java/eirb/pg203/exceptions/WeatherFetchingException.java +++ b/src/main/java/eirb/pg203/exceptions/WeatherFetchingException.java @@ -1,6 +1,13 @@ package eirb.pg203.exceptions; +/** + * Exception when an error during the api call + */ public class WeatherFetchingException extends Exception { + /** + * Weather Fetching exception + * @param message message of the exception + */ public WeatherFetchingException(String message) { super(message); } diff --git a/src/main/java/eirb/pg203/utils/Coords.java b/src/main/java/eirb/pg203/utils/Coords.java index 9f58cb7..4308549 100644 --- a/src/main/java/eirb/pg203/utils/Coords.java +++ b/src/main/java/eirb/pg203/utils/Coords.java @@ -1,26 +1,50 @@ package eirb.pg203.utils; +/** + * Coordinates representation + */ public class Coords { private float lat; private float lon; + /** + * Coordinates representation + * @param lat latitude + * @param lon longitude + */ public Coords(float lat, float lon) { this.lat = lat; this.lon = lon; } + /** + * Get latitude + * @return latitude + */ public float getLat() { return lat; } + /** + * Get longitude + * @return longitude + */ public float getLon() { return lon; } + /** + * Set latitude + * @param lat latitude + */ public void setLat(float lat) { this.lat = lat; } + /** + * Set longitude + * @param lon longitude + */ public void setLon(float lon) { this.lon = lon; } diff --git a/src/main/java/eirb/pg203/utils/JSONFetcher.java b/src/main/java/eirb/pg203/utils/JSONFetcher.java index bf3d928..079a0b8 100644 --- a/src/main/java/eirb/pg203/utils/JSONFetcher.java +++ b/src/main/java/eirb/pg203/utils/JSONFetcher.java @@ -9,8 +9,21 @@ import java.net.URL; import org.json.JSONArray; import org.json.JSONObject; +/** + * Util for http calls + */ public class JSONFetcher { + /** + * No need for constructor + */ + private JSONFetcher() {}; + /** + * Make the request + * @param url url to fetch + * @return String of the response + * @throws IOException if the request failed + */ private static String fetchString(URL url) throws IOException{ StringBuilder result = new StringBuilder(); HttpURLConnection conn = (HttpURLConnection) url.openConnection(); @@ -24,13 +37,25 @@ public class JSONFetcher { return result.toString(); } - + + /** + * Fetch an url + * @param url url + * @return Json object of the response + * @throws IOException if the request failed + */ public static JSONObject fetch(URL url) throws IOException { String result = fetchString(url); return new JSONObject(result); } + /** + * Fetch a Json array from an url + * @param url url + * @return JSON array + * @throws IOException when request failed + */ public static JSONArray fetchArray(URL url) throws IOException { String result = fetchString(url);