From c6242c6b14c9b47301b7cecebc339b2259efd116 Mon Sep 17 00:00:00 2001
From: Tobias Schneider <Tobias.Schneider@Tobsch.org>
Date: Mon, 23 Dec 2024 12:42:50 +0100
Subject: [PATCH] improve the javadoc for the spi package

---
 .../jollyday/core/spi/ChristianHoliday.java   |  2 +-
 .../core/spi/ConfigurationService.java        | 11 +++-
 .../core/spi/EthiopianOrthodoxHoliday.java    |  2 +-
 .../focus_shift/jollyday/core/spi/Fixed.java  | 16 ++++++
 .../jollyday/core/spi/Holidays.java           | 54 +++++++++++++++++++
 .../jollyday/core/spi/IslamicHoliday.java     |  2 +-
 6 files changed, 83 insertions(+), 4 deletions(-)

diff --git a/jollyday-core/src/main/java/de/focus_shift/jollyday/core/spi/ChristianHoliday.java b/jollyday-core/src/main/java/de/focus_shift/jollyday/core/spi/ChristianHoliday.java
index aed23d95d..cd172e1b8 100644
--- a/jollyday-core/src/main/java/de/focus_shift/jollyday/core/spi/ChristianHoliday.java
+++ b/jollyday-core/src/main/java/de/focus_shift/jollyday/core/spi/ChristianHoliday.java
@@ -3,7 +3,7 @@
 import java.time.chrono.Chronology;
 
 /**
- * Represents a christian holiday that can be
+ * Represents the configuration of a christian holiday that can be
  *
  * <ul>
  *   <li>Movable</li>
diff --git a/jollyday-core/src/main/java/de/focus_shift/jollyday/core/spi/ConfigurationService.java b/jollyday-core/src/main/java/de/focus_shift/jollyday/core/spi/ConfigurationService.java
index 1fdbf03bb..ccfcd22b2 100644
--- a/jollyday-core/src/main/java/de/focus_shift/jollyday/core/spi/ConfigurationService.java
+++ b/jollyday-core/src/main/java/de/focus_shift/jollyday/core/spi/ConfigurationService.java
@@ -3,10 +3,19 @@
 import de.focus_shift.jollyday.core.ManagerParameter;
 
 /**
- * Service to provide the serialised configuration from XML files.
+ * This interface provides the way to receive the serialized holiday configuration
+ * on the base of the xml files for a specific country or special calendar.
  */
 public interface ConfigurationService {
 
+  /**
+   * Returns the configuration based on the {@link ManagerParameter}.
+   * <p>
+   * In most cases the configuration is based on the countries ISO code 3166.
+   *
+   * @param parameter to identify the country or special calendar configuration
+   * @return the holiday configuration of a country
+   */
   Configuration getConfiguration(ManagerParameter parameter);
 
 }
diff --git a/jollyday-core/src/main/java/de/focus_shift/jollyday/core/spi/EthiopianOrthodoxHoliday.java b/jollyday-core/src/main/java/de/focus_shift/jollyday/core/spi/EthiopianOrthodoxHoliday.java
index 3aad0552d..6e16d7ff7 100644
--- a/jollyday-core/src/main/java/de/focus_shift/jollyday/core/spi/EthiopianOrthodoxHoliday.java
+++ b/jollyday-core/src/main/java/de/focus_shift/jollyday/core/spi/EthiopianOrthodoxHoliday.java
@@ -1,7 +1,7 @@
 package de.focus_shift.jollyday.core.spi;
 
 /**
- * Represents an ethiopian orthodox holiday that can be
+ * Represents the configuration of an ethiopian orthodox holiday that can be
  *
  * <ul>
  *   <li>Limited</li>
diff --git a/jollyday-core/src/main/java/de/focus_shift/jollyday/core/spi/Fixed.java b/jollyday-core/src/main/java/de/focus_shift/jollyday/core/spi/Fixed.java
index 32e2118bb..26d3c4026 100644
--- a/jollyday-core/src/main/java/de/focus_shift/jollyday/core/spi/Fixed.java
+++ b/jollyday-core/src/main/java/de/focus_shift/jollyday/core/spi/Fixed.java
@@ -2,8 +2,24 @@
 
 import java.time.MonthDay;
 
+/**
+ * Represents the configuration of a holiday that can be
+ *
+ * <ul>
+ *   <li>Movable</li>
+ *   <li>Limited</li>
+ *   <li>Described</li>
+ * </ul>
+ *
+ * and occurs on the same day and month on every year.
+ */
 public interface Fixed extends Described, Movable, Limited {
 
+  /**
+   * Contains the information on which day and month this holiday occurs.
+   *
+   * @return month and day on which this holiday will occur
+   */
   MonthDay day();
 
 }
diff --git a/jollyday-core/src/main/java/de/focus_shift/jollyday/core/spi/Holidays.java b/jollyday-core/src/main/java/de/focus_shift/jollyday/core/spi/Holidays.java
index 954ae3058..594346b46 100644
--- a/jollyday-core/src/main/java/de/focus_shift/jollyday/core/spi/Holidays.java
+++ b/jollyday-core/src/main/java/de/focus_shift/jollyday/core/spi/Holidays.java
@@ -2,26 +2,80 @@
 
 import java.util.List;
 
+/**
+ * Represents the configurations for all holidays
+ * for a specific country or special calendar.
+ */
 public interface Holidays {
 
+  /**
+   * see {@link Fixed}
+   *
+   * @return list of all fixed holidays
+   */
   List<Fixed> fixed();
 
+    /**
+   * see {@link RelativeToFixed}
+   *
+   * @return list of relativeToFixed configurations
+   */
   List<RelativeToFixed> relativeToFixed();
 
+    /**
+   * see {@link RelativeToWeekdayInMonth}
+   *
+   * @return list of all relativeToWeekdayInMonth configurations
+   */
   List<RelativeToWeekdayInMonth> relativeToWeekdayInMonth();
 
+    /**
+   * see {@link FixedWeekdayInMonth}
+   *
+   * @return list of all fixedWeekdays configurations
+   */
   List<FixedWeekdayInMonth> fixedWeekdays();
 
+    /**
+   * see {@link ChristianHoliday}
+   *
+   * @return list of all christianHolidays configurations
+   */
   List<ChristianHoliday> christianHolidays();
 
+    /**
+   * see {@link IslamicHoliday}
+   *
+   * @return list of islamicHolidays fixed configurations
+   */
   List<IslamicHoliday> islamicHolidays();
 
+    /**
+   * see {@link FixedWeekdayBetweenFixed}
+   *
+   * @return list of all fixedWeekdayBetweenFixed configurations
+   */
   List<FixedWeekdayBetweenFixed> fixedWeekdayBetweenFixed();
 
+    /**
+   * see {@link FixedWeekdayRelativeToFixed}
+   *
+   * @return list of all fixedWeekdayRelativeToFixed configurations
+   */
   List<FixedWeekdayRelativeToFixed> fixedWeekdayRelativeToFixed();
 
+    /**
+   * see {@link EthiopianOrthodoxHoliday}
+   *
+   * @return list of all ethiopianOrthodoxHolidays configurations
+   */
   List<EthiopianOrthodoxHoliday> ethiopianOrthodoxHolidays();
 
+    /**
+   * see {@link RelativeToEasterSunday}
+   *
+   * @return list of all relativeToEasterSunday configurations
+   */
   List<RelativeToEasterSunday> relativeToEasterSunday();
 
 }
diff --git a/jollyday-core/src/main/java/de/focus_shift/jollyday/core/spi/IslamicHoliday.java b/jollyday-core/src/main/java/de/focus_shift/jollyday/core/spi/IslamicHoliday.java
index eecd3c1b7..dd810719f 100644
--- a/jollyday-core/src/main/java/de/focus_shift/jollyday/core/spi/IslamicHoliday.java
+++ b/jollyday-core/src/main/java/de/focus_shift/jollyday/core/spi/IslamicHoliday.java
@@ -1,7 +1,7 @@
 package de.focus_shift.jollyday.core.spi;
 
 /**
- * Represents a islamic holiday that can be
+ * Represents the configuration of an islamic holiday that can be
  *
  * <ul>
  *   <li>Movable</li>