From c7b23335b52080b0c9a83229fb91f6d6d2f1b054 Mon Sep 17 00:00:00 2001 From: David Guler Date: Mon, 5 Dec 2022 15:26:10 +0100 Subject: [PATCH] doc: javadoc for types --- .../gartenverwaltung/io/JsonTaskList.java | 2 +- .../ch/zhaw/gartenverwaltung/types/Crop.java | 6 +-- .../gartenverwaltung/types/GrowthPhase.java | 14 +++++- .../types/GrowthPhaseType.java | 4 ++ .../ch/zhaw/gartenverwaltung/types/Pest.java | 7 +++ .../ch/zhaw/gartenverwaltung/types/Plant.java | 41 +++++++++++++--- .../zhaw/gartenverwaltung/types/Seasons.java | 4 ++ .../ch/zhaw/gartenverwaltung/types/Task.java | 49 ++++++++++++++++--- .../gartenverwaltung/types/TaskTemplate.java | 7 +++ .../gartenverwaltung/types/WateringCycle.java | 7 +++ 10 files changed, 124 insertions(+), 17 deletions(-) diff --git a/src/main/java/ch/zhaw/gartenverwaltung/io/JsonTaskList.java b/src/main/java/ch/zhaw/gartenverwaltung/io/JsonTaskList.java index 5b1cb96..8183afb 100644 --- a/src/main/java/ch/zhaw/gartenverwaltung/io/JsonTaskList.java +++ b/src/main/java/ch/zhaw/gartenverwaltung/io/JsonTaskList.java @@ -71,7 +71,7 @@ public class JsonTaskList implements TaskList { if(taskMap.isEmpty()) { loadTaskListFromFile(); } - return taskMap.values().stream().filter(task -> task.isInTimePeriode(start, end)).toList(); + return taskMap.values().stream().filter(task -> task.isInTimePeriod(start, end)).toList(); } /** diff --git a/src/main/java/ch/zhaw/gartenverwaltung/types/Crop.java b/src/main/java/ch/zhaw/gartenverwaltung/types/Crop.java index 58cd453..e5ea19b 100644 --- a/src/main/java/ch/zhaw/gartenverwaltung/types/Crop.java +++ b/src/main/java/ch/zhaw/gartenverwaltung/types/Crop.java @@ -1,12 +1,12 @@ package ch.zhaw.gartenverwaltung.types; -import ch.zhaw.gartenverwaltung.io.JsonPlantList; -import ch.zhaw.gartenverwaltung.io.PlantList; - import java.time.LocalDate; import java.util.Objects; import java.util.Optional; +/** + * Represents a crop, meaning a specific plant growing at a specific time. + */ public class Crop { private Long cropId = null; private final long plantId; diff --git a/src/main/java/ch/zhaw/gartenverwaltung/types/GrowthPhase.java b/src/main/java/ch/zhaw/gartenverwaltung/types/GrowthPhase.java index 6efcc44..c5c80cd 100644 --- a/src/main/java/ch/zhaw/gartenverwaltung/types/GrowthPhase.java +++ b/src/main/java/ch/zhaw/gartenverwaltung/types/GrowthPhase.java @@ -7,7 +7,19 @@ import com.fasterxml.jackson.databind.annotation.JsonDeserialize; import java.time.MonthDay; import java.util.List; - +/** + * Represents a growth phase of a plant. + * Plants go through several phases during their life (sowing, germinating, growing, ..., harvest). + * These phases are characterized by what kinds of tasks need to be executed by the gardener to stay alive. + * This class represents one such phase. + * + * @param startDate The earliest date on which this phase can start + * @param endDate The latest date on which this phase can start + * @param group Which group this phase belongs to (if the growth phase can occur multiple times a year, default: 0) + * @param type What {@link GrowthPhaseType} this represents + * @param zone The hardiness zone for which this growth phase is valid + * @param taskTemplates The (undated) tasks required to be performed by the gardener + */ public record GrowthPhase( MonthDay startDate, MonthDay endDate, diff --git a/src/main/java/ch/zhaw/gartenverwaltung/types/GrowthPhaseType.java b/src/main/java/ch/zhaw/gartenverwaltung/types/GrowthPhaseType.java index 96609cc..4a3ef38 100644 --- a/src/main/java/ch/zhaw/gartenverwaltung/types/GrowthPhaseType.java +++ b/src/main/java/ch/zhaw/gartenverwaltung/types/GrowthPhaseType.java @@ -1,5 +1,9 @@ package ch.zhaw.gartenverwaltung.types; +/** + * Enumerates the different possible types of {@link GrowthPhase}. + * (Subject to later expansion) + */ public enum GrowthPhaseType { SOW, PLANT, REPLANT, HARVEST } diff --git a/src/main/java/ch/zhaw/gartenverwaltung/types/Pest.java b/src/main/java/ch/zhaw/gartenverwaltung/types/Pest.java index cfbcb81..a1dbc2d 100644 --- a/src/main/java/ch/zhaw/gartenverwaltung/types/Pest.java +++ b/src/main/java/ch/zhaw/gartenverwaltung/types/Pest.java @@ -1,4 +1,11 @@ package ch.zhaw.gartenverwaltung.types; +/** + * Represents a pest or pathogen which may afflict a plant. + * + * @param name The name of the pest + * @param description A description of the pest + * @param measures Measures that can be taken against the pest. + */ public record Pest(String name, String description, String measures) { } diff --git a/src/main/java/ch/zhaw/gartenverwaltung/types/Plant.java b/src/main/java/ch/zhaw/gartenverwaltung/types/Plant.java index d602f51..dd92412 100644 --- a/src/main/java/ch/zhaw/gartenverwaltung/types/Plant.java +++ b/src/main/java/ch/zhaw/gartenverwaltung/types/Plant.java @@ -9,6 +9,20 @@ import java.util.stream.Collectors; import static java.time.temporal.ChronoUnit.DAYS; +/** + * Represents a plant + * + * @param id A unique identifier + * @param name The name of the plant + * @param description A description of the plant + * @param image An image representing the plant + * @param spacing The amount of space needed between individual plants of this type + * @param light The amount of light preferred by the plant (h/d) + * @param soil The type of soil required for the plant + * @param pests {@link Pest}s that may afflict the plant + * @param wateringCycle The {@link WateringCycle} required by the plant + * @param lifecycle A list of {@link GrowthPhase}s constituting the plants lifecycle + */ public record Plant( long id, String name, @@ -30,9 +44,10 @@ public record Plant( } /** - * get all growthPhases of lifecycle group - * @param group lifecycle group - * @return list of growthPhases + * Get all {@link GrowthPhase}s of a lifecycle group + * + * @param group The lifecycle group + * @return A list of {@link GrowthPhase}s */ public List lifecycleForGroup(int group) { return lifecycle.stream() @@ -40,6 +55,12 @@ public record Plant( .collect(Collectors.toList()); } + /** + * Given a {@link LocalDate}, determines which lifecycle group contains it. + * + * @param date The date to look for + * @return Which lifecycle group the date is in + */ public int getGrowphaseGroupForDate(LocalDate date) { for(GrowthPhase growthPhase : lifecycle){ MonthDay plantingDate = MonthDay.of(date.getMonth().getValue(), date.getDayOfMonth()); @@ -51,16 +72,18 @@ public record Plant( } /** - * get sow date from given harvest day from lifecycle group + * Get sow date from given harvest date from lifecycle group + * * @param harvestDate date of the harvest - * @return LocaleDate of sow date + * @return {@link LocalDate} of sow date */ public LocalDate sowDateFromHarvestDate(LocalDate harvestDate) { return harvestDate.minusDays(timeToHarvest(lifecycleGroupFromHarvestDate(harvestDate))); } /** - * calculate the days between sow and harvest day for lifecycle group + * Calculate the number of days between sow and harvest date for lifecycle group + * * @param group the lifecycle group * @return Integer number of dates between sow and harvest day */ @@ -79,6 +102,12 @@ public record Plant( return (int) DAYS.between(sow.startDate().atYear(currentYear),harvest.startDate().atYear(currentYear)); } + /** + * Given a harvest date, determines which lifecycle group it belongs to. + * + * @param harvestDate The harvest date + * @return Which lifecycle group the harvest date is in + */ public int lifecycleGroupFromHarvestDate(LocalDate harvestDate) { return lifecycle.stream() .filter(growthPhase -> growthPhase.type().equals(GrowthPhaseType.HARVEST) && diff --git a/src/main/java/ch/zhaw/gartenverwaltung/types/Seasons.java b/src/main/java/ch/zhaw/gartenverwaltung/types/Seasons.java index fd2601c..311c078 100644 --- a/src/main/java/ch/zhaw/gartenverwaltung/types/Seasons.java +++ b/src/main/java/ch/zhaw/gartenverwaltung/types/Seasons.java @@ -2,6 +2,10 @@ package ch.zhaw.gartenverwaltung.types; import java.time.MonthDay; +/** + * Describes the 4 Seasons in terms of {@link java.time.LocalDate}s + * Also describes "All Seasons" as the full year. + */ public enum Seasons { ALLSEASONS("--01-01", "--12-31", "All Seasons"), SPRING("--03-01", "--05-30", "Spring"), diff --git a/src/main/java/ch/zhaw/gartenverwaltung/types/Task.java b/src/main/java/ch/zhaw/gartenverwaltung/types/Task.java index ef97003..017b18f 100644 --- a/src/main/java/ch/zhaw/gartenverwaltung/types/Task.java +++ b/src/main/java/ch/zhaw/gartenverwaltung/types/Task.java @@ -1,11 +1,10 @@ package ch.zhaw.gartenverwaltung.types; - import java.time.LocalDate; import java.util.Optional; /** - * Models a Task + * Represents a Task * May be created using the builder pattern. */ public class Task { @@ -18,10 +17,9 @@ public class Task { private LocalDate nextExecution; private LocalDate nextNotification; private long cropId; - private boolean done; /** - * default constructor + * Default constructor * (used by Json deserializer) */ public Task(){ @@ -32,6 +30,14 @@ public class Task { nextExecution = startDate; } + /** + * Constructor for a non-repeating task related to a {@link Crop} + * + * @param name The name of the task + * @param description A description of the task + * @param startDate The start date of the task + * @param cropId The id of the crop to which the task belongs + */ public Task(String name, String description, LocalDate startDate, long cropId) { this.name = name; this.description = description; @@ -43,7 +49,12 @@ public class Task { /** * Constructor for weather events - */ + * + * @param name The name of the task + * @param description A description of the task + * @param startDate The start date of the task + * @param endDate The maximum date on which the task should be executed + */ public Task(String name, String description, LocalDate startDate, LocalDate endDate) { this.name = name; this.description = description; @@ -51,6 +62,16 @@ public class Task { this.endDate = endDate; } + /** + * Full constructor (without id) + * + * @param name The name of the task + * @param description A description of the task + * @param startDate The start date of the task + * @param endDate The maximum date on which the task should be executed + * @param interval The number of days between executions + * @param cropId The id of the crop to which the task belongs + */ public Task(String name, String description, LocalDate startDate, LocalDate endDate, int interval, long cropId) { this.name = name; this.description = description; @@ -75,10 +96,20 @@ public class Task { return this; } - public boolean isInTimePeriode(LocalDate searchStartDate, LocalDate searchEndDate){ + /** + * Checks if the Task is within a specific date range. + * + * @param searchStartDate The minimum date + * @param searchEndDate The maximum date + * @return Whether the Task is within the given range + */ + public boolean isInTimePeriod(LocalDate searchStartDate, LocalDate searchEndDate) { return endDate.isAfter(searchStartDate) && startDate.isBefore(searchEndDate); } + /** + * Marks a specific execution of a Task as done. + */ public void done(){ if(interval != null && interval != 0 && !nextExecution.plusDays(interval).isAfter(endDate)){ nextExecution = nextExecution.plusDays(interval); @@ -117,6 +148,12 @@ public class Task { return Optional.ofNullable(endDate); } + /** + * Updates the fields of this Task using the values of the given Task + * + * @param task The task whose fields to copy + * @return This task with the fields already updated + */ public Task updateTask(Task task) { this.name = task.getName(); this.description = task.getDescription(); diff --git a/src/main/java/ch/zhaw/gartenverwaltung/types/TaskTemplate.java b/src/main/java/ch/zhaw/gartenverwaltung/types/TaskTemplate.java index 39e349f..6e5fc7a 100644 --- a/src/main/java/ch/zhaw/gartenverwaltung/types/TaskTemplate.java +++ b/src/main/java/ch/zhaw/gartenverwaltung/types/TaskTemplate.java @@ -41,6 +41,13 @@ public class TaskTemplate { this.relativeStartDate = relativeStartDate; } + /** + * Create a concrete {@link Task} given a concrete start date + * + * @param realStartDate The start date of the {@link GrowthPhase} to which the {@link #relativeStartDate} is relative. + * @param cropId The crop for which the task should be generated. + * @return The created {@link Task} + */ public Task generateTask(LocalDate realStartDate, long cropId) { LocalDate endDate = relativeEndDate != null ? realStartDate.plusDays(relativeEndDate) : realStartDate; diff --git a/src/main/java/ch/zhaw/gartenverwaltung/types/WateringCycle.java b/src/main/java/ch/zhaw/gartenverwaltung/types/WateringCycle.java index 9d7c7d0..5ac9778 100644 --- a/src/main/java/ch/zhaw/gartenverwaltung/types/WateringCycle.java +++ b/src/main/java/ch/zhaw/gartenverwaltung/types/WateringCycle.java @@ -1,5 +1,12 @@ package ch.zhaw.gartenverwaltung.types; +/** + * Describes the cycle in which a {@link Plant} should be watered + * + * @param litersPerSqM How many litres of water per square metre of ground + * @param interval The interval (days) + * @param notes Notes on the cycle + */ public record WateringCycle( int litersPerSqM, int interval,