improve the javadoc for the spi package

focus-shift · Dec 23, 2024 · c6242c6 · c6242c6
1 parent 1401d1e
commit c6242c6
Show file tree

Hide file tree

Showing 6 changed files with 83 additions and 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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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>