From a7ec614471e6b36ac6b773419bb4a552a0ca2a12 Mon Sep 17 00:00:00 2001 From: Martin Eyben Date: Tue, 19 Nov 2024 17:43:20 +0100 Subject: [PATCH] feat: documentation --- src/main/java/eirb/pg203/WeatherData.java | 71 +++++++++++++++++-- src/main/java/eirb/pg203/WeatherDataAPI.java | 10 +++ .../java/eirb/pg203/WeatherDisplayBasic.java | 53 ++++++++++++-- 3 files changed, 124 insertions(+), 10 deletions(-) diff --git a/src/main/java/eirb/pg203/WeatherData.java b/src/main/java/eirb/pg203/WeatherData.java index c069d85..0b558ed 100644 --- a/src/main/java/eirb/pg203/WeatherData.java +++ b/src/main/java/eirb/pg203/WeatherData.java @@ -4,14 +4,18 @@ import java.time.Instant; import java.util.concurrent.locks.Condition; public class WeatherData { - enum Condition { + + /** + * Representation of a weather condition (with a smiley for String representation) + */ + public enum Condition { SUNNY("☀️"), PARTIAL("🌤"), CLOUDY("☁️"), RAINY("🌧"), ERROR("E"); - private String desc; + private final String desc; Condition(String desc) { this.desc = desc; } @Override @@ -20,7 +24,10 @@ public class WeatherData { } } - enum WindDirection { + /** + * Representation of the wind direction with an arrow + */ + public enum WindDirection { N("🡩"), NE("🡭"), E("🡪"), @@ -31,7 +38,7 @@ public class WeatherData { NW("🡬"), ERROR("E"); - private String desc; + private final String desc; WindDirection(String desc) {this.desc = desc;} @Override @@ -45,9 +52,14 @@ public class WeatherData { private Condition condition; // cloudly, sunny ... private float windSpeed; private float windDirectionAngle; - private WindDirection windDirection; + private final WindDirection windDirection; + /** + * Get wind direction representation based on the angle + * @param windDirectionAngle float representation of the wind direction + * @return wind direction representation + */ private WindDirection getWindDirection(float windDirectionAngle) { if (windDirectionAngle >= 337.5 || windDirectionAngle <= 22.5) return WindDirection.N; @@ -69,6 +81,7 @@ public class WeatherData { return WindDirection.ERROR; } + WeatherData(City city, Instant date, float temp, float windSpeed, float windDirectionAngle, Condition condition) { this.city = city; this.date = date; @@ -79,56 +92,104 @@ public class WeatherData { this.windDirection = this.getWindDirection(windDirectionAngle); } + /** + * @return city + */ public City getCity() { return city; } + /** + * + * @return date of the Weather data + */ public Instant getDate() { return date; } + /** + * @return Weather Condition representation + */ public Condition getCondition() { return condition; } + /** + * @return float temperature + */ public float getTemp() { return temp; } + /** + * @return wind speed + */ public float getWindSpeed() { return windSpeed; } + /** + * @return Wind direction angle + */ public float getWindDirectionAngle() {return this.windDirectionAngle;} + /** + * @return wind direction representation + */ public WindDirection getWindDirection() { return windDirection; } + /** + * Set city + * @param city city of the weather representation + */ public void setCity(City city) { this.city = city; } + /** + * Set date of the weather data + * @param date date + */ public void setDate(Instant date) { this.date = date; } + /** + * Set weather data representation + * @param condition weather data representation + */ public void setCondition(Condition condition) { this.condition = condition; } + /** + * @param temp Weather data temperature + */ public void setTemp(float temp) { this.temp = temp; } + /** + * @param windSpeed Wind speed + */ public void setWindSpeed(float windSpeed) { this.windSpeed = windSpeed; } + /** + * @param windDirectionAngle wind direction angle + */ public void setWindDirectionAngle(float windDirectionAngle) { this.windDirectionAngle = windDirectionAngle; } + /** + * WeatherData representation + * 10,70° 🌧 25,80km/h 243,00° 🡯 + * @return String representation of the WeatherData + */ @Override public String toString() { return String.format("%05.2f° %s %05.2fkm/h %06.2f° %s", diff --git a/src/main/java/eirb/pg203/WeatherDataAPI.java b/src/main/java/eirb/pg203/WeatherDataAPI.java index ccea000..ab269f7 100644 --- a/src/main/java/eirb/pg203/WeatherDataAPI.java +++ b/src/main/java/eirb/pg203/WeatherDataAPI.java @@ -3,6 +3,9 @@ package eirb.pg203; import java.io.IOException; import java.util.ArrayList; +/** + * Interface to discuss with a weather API + */ public interface WeatherDataAPI { /** @@ -24,6 +27,13 @@ public interface WeatherDataAPI { */ WeatherData getTemperature(int day, int hour, String city) throws IOException; + /** + * Fetch the temperature for multiple day since today + * @param days number of days to fetch + * @param city name of te city + * @return List of WeatherData + * @throws IOException when request failed + */ ArrayList getTemperatures(int days, String city) throws IOException; /*** diff --git a/src/main/java/eirb/pg203/WeatherDisplayBasic.java b/src/main/java/eirb/pg203/WeatherDisplayBasic.java index d224da1..dddc38c 100644 --- a/src/main/java/eirb/pg203/WeatherDisplayBasic.java +++ b/src/main/java/eirb/pg203/WeatherDisplayBasic.java @@ -4,12 +4,18 @@ import java.util.ArrayList; import java.util.HashMap; class WeatherDisplayBasic implements WeatherDisplay { - private ArrayList apis; - - WeatherDisplayBasic() { - this.apis = new ArrayList(); - } + /** + * List of apis + */ + private final ArrayList apis = new ArrayList<>(); + /** + * Display header + * Source J + 0 J + 1 J + 2 + * @param days number of columns + * @param sourceColumnSize size of the first column + * @param dayColumnSize day column size + */ private void displayHeader(int days, double sourceColumnSize, double dayColumnSize) { StringBuilder line = new StringBuilder(); line.append("Source\t"); @@ -26,6 +32,13 @@ class WeatherDisplayBasic implements WeatherDisplay { System.out.println(line); } + /** + * Calculate column size based on the WeatherData + * Check the size of the string of the weather data and return the max for the column + * WARNING : Special chars in the WeatherData string will introduce an offset + * @param weatherDataAPIArrayListHashMap list of Weather data for every WeatherDataApi + * @return day column size + */ private double getColumnSize(HashMap> weatherDataAPIArrayListHashMap) { double max = 0; for (WeatherDataAPI api: weatherDataAPIArrayListHashMap.keySet()) { @@ -39,6 +52,15 @@ class WeatherDisplayBasic implements WeatherDisplay { return max; } + /** + * Display a line of data with a column separator + * OpenWeatherMap | 14,49° ☁️ 07,71km/h 254,25° 🡨 | 11,29° ☁️ 04,33km/h 296,00° 🡬 | 12,06° ☁️ 07,53km/h 188,88° 🡫 | + * @param apiName Name of the api if the first column + * @param weatherDatas List of Weather data to display + * @param startColumnString Separator between column + * @param sourceColumnSize Size of the first column + * @param dayColumnSize Size for day columns + */ private void displayWeatherDatas(String apiName, ArrayList weatherDatas, String startColumnString, double sourceColumnSize, double dayColumnSize) { StringBuilder line = new StringBuilder(); String weatherDataString; @@ -61,6 +83,13 @@ class WeatherDisplayBasic implements WeatherDisplay { } + /** + * Display in stdout the line between apis + * -------------------------------+------------------------------+------------------------------+------------------------------+ + * @param days number of days to display + * @param sourceColumnSize size for the first column (where the name of the api is display) + * @param dayColumnSize column size for the days (where the temperature is displayed) + */ private void displaySeparatorLine(int days, double sourceColumnSize, double dayColumnSize) { String mainSeparator = "-"; String secondSeparator = "+"; @@ -77,6 +106,20 @@ class WeatherDisplayBasic implements WeatherDisplay { System.out.println(line); } + /** + * Display an array like this in stdout + * Source J + 0 J + 1 J + 2 + * -------------------------------+------------------------------+------------------------------+------------------------------+ + * OpenWeatherMap | 14,49° ☁️ 07,71km/h 254,25° 🡨 | 11,29° ☁️ 04,33km/h 296,00° 🡬 | 12,06° ☁️ 07,53km/h 188,88° 🡫 | + * -------------------------------+------------------------------+------------------------------+------------------------------+ + * WeatherAPI | 12,50° 🌧 20,31km/h 238,67° 🡯 | 11,20° 🌧 17,23km/h 291,92° 🡨 | 11,00° 🌧 25,59km/h 256,88° 🡨 | + * -------------------------------+------------------------------+------------------------------+------------------------------+ + * OpenMeteo | 10,70° 🌧 25,80km/h 243,00° 🡯 | 11,35° 🌧 24,30km/h 276,00° 🡨 | 11,00° 🌧 31,50km/h 238,00° 🡯 | + * -------------------------------+------------------------------+------------------------------+------------------------------+ + * + * @param weatherDataAPIArrayListHashMap Hashmap with WeatherData array for each api + * @param days number of days to display + */ private void displayAllWeatherDatas(HashMap> weatherDataAPIArrayListHashMap, int days) { double dayColumnSize = this.getColumnSize(weatherDataAPIArrayListHashMap);