improve the javadoc for the spi package

jollyday-core/src/main/java/de/focus_shift/jollyday/core/parser/impl/RelativeToFixedParser.java

@@ -28,13 +28,15 @@ public List<Holiday> parse(final Year year, final Holidays holidays) {
         LocalDate fixed = new FixedToLocalDate(year).apply(rf.date());
         if (rf.weekday() != null) {
           // if weekday is set -> move to weekday
-          DayOfWeek day = rf.weekday();
-          int direction = (rf.when() == Relation.BEFORE ? -1 : 1);
+          final DayOfWeek day = rf.weekday();
+          final int direction = (rf.when() == Relation.BEFORE ? -1 : 1);
           // don't test start day
           fixed = fixed.plusDays(direction);
+
           while (fixed.getDayOfWeek() != day) {
             fixed = fixed.plusDays(direction);
           }
+
         } else if (rf.days() != null) {
           // if number of days set -> move number of days
           fixed = fixed.plus(rf.when() == Relation.BEFORE ? rf.days().negated() : rf.days());

jollyday-core/src/main/java/de/focus_shift/jollyday/core/spi/ChristianHoliday.java

@@ -3,21 +3,24 @@
 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>
  *   <li>Limited</li>
  *   <li>Described</li>
  * </ul>
- *
+ * <p>
  * and has a special {@link ChristianHolidayType} and a chronology based on {@link Chronology}.
+ * <p>
  * Two chronologies are supported:
  * <ul>
  *   <li>ISO</li>
  *   <li>Julian</li>
  * </ul>
- *
+ * <p>
+ * Example: All christian holidays are relative to Easter Sunday e.g. carnival is 47 days after Easter Sunday.
+ * <p>
  * The {@link de.focus_shift.jollyday.core.parser.impl.ChristianHolidayParser} is used.
  */
 public interface ChristianHoliday extends Limited, Described, Movable {

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);
 
 }

jollyday-core/src/main/java/de/focus_shift/jollyday/core/spi/EthiopianOrthodoxHoliday.java

@@ -1,16 +1,16 @@
 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>
  *   <li>Described</li>
  * </ul>
- *
+ * <p>
  * and has a special {@link EthiopianOrthodoxHolidayType}.
+ * <p>
  * The {@link de.focus_shift.jollyday.core.parser.impl.EthiopianOrthodoxHolidayParser} is used.
- *
  */
 public interface EthiopianOrthodoxHoliday extends Described, Limited {
 

jollyday-core/src/main/java/de/focus_shift/jollyday/core/spi/Fixed.java

@@ -2,8 +2,28 @@
 
 import java.time.MonthDay;
 
+/**
+ * Represents the configuration of a holiday that can be
+ *
+ * <ul>
+ *   <li>Movable</li>
+ *   <li>Limited</li>
+ *   <li>Described</li>
+ * </ul>
+ * <p>
+ * and occurs on the same day and month on every year.
+ * <p>
+ * Example: A holiday on the first January, like New Year.
+ * <p>
+ * The {@link de.focus_shift.jollyday.core.parser.impl.FixedParser} is used.
+ */
 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();
 
 }

jollyday-core/src/main/java/de/focus_shift/jollyday/core/spi/FixedWeekdayBetweenFixed.java

@@ -2,12 +2,42 @@
 
 import java.time.DayOfWeek;
 
+/**
+ * Represents the configuration of a fixed weekday holiday between two other {@link Fixed} holidays/days that can be
+ *
+ * <ul>
+ *   <li>Limited</li>
+ *   <li>Described</li>
+ * </ul>
+ * <p>
+ * The `from` and `to` describes the date range in which the `weekday` is a holiday.
+ * <p>
+ * Example: The holiday is the Saturday between the first January and the 10th January.
+ * If there are multiple Saturdays between the two dates all will be returned.
+ * <p>
+ * The {@link de.focus_shift.jollyday.core.parser.impl.FixedWeekdayBetweenFixedParser} is used.
+ */
 public interface FixedWeekdayBetweenFixed extends Described, Limited {
 
+  /**
+   * Start of the date range in which the weekday occurs
+   *
+   * @return the {@link Fixed} start date of the date range
+   */
   Fixed from();
 
+  /**
+   * End of the date range in which the weekday occurs
+   *
+   * @return the {@link Fixed} end date of the date range
+   */
   Fixed to();
 
+  /**
+   * The weekday which represents the holiday between from and to
+   *
+   * @return the weekday for the holiday
+   */
   DayOfWeek weekday();
 
 }

jollyday-core/src/main/java/de/focus_shift/jollyday/core/spi/FixedWeekdayInMonth.java

@@ -3,12 +3,39 @@
 import java.time.DayOfWeek;
 import java.time.Month;
 
+/**
+ * Represents the configuration of a holiday that has a fixed weekday in a month based on its occurrence that can be
+ *
+ * <ul>
+ *   <li>Limited</li>
+ *   <li>Described</li>
+ * </ul>
+ * <p>
+ * Example: The first Saturday in January.
+ * <p>
+ * The {@link de.focus_shift.jollyday.core.parser.impl.FixedWeekdayInMonthParser} is used.
+ */
 public interface FixedWeekdayInMonth extends Described, Limited {
 
+  /**
+   * Describes the day of the week, like Monday, Tuesday, ...
+   *
+   * @return the weekday on which the holiday occurs
+   */
   DayOfWeek weekday();
 
+  /**
+   * Describes the month in which the holiday will occur.
+   *
+   * @return the month in which the holiday occurs
+   */
   Month month();
 
+  /**
+   * Describes on which weekday the holiday occurs, like the first or second
+   *
+   * @return the occurrence
+   */
   Occurrence which();
 
 }

jollyday-core/src/main/java/de/focus_shift/jollyday/core/spi/FixedWeekdayRelativeToFixed.java

@@ -2,14 +2,52 @@
 
 import java.time.DayOfWeek;
 
+/**
+ * Represents the configuration of a holiday that occurs on a fixed weekday
+ * relative to a {@link Fixed} holiday that can be
+ *
+ * <ul>
+ *   <li>Limited</li>
+ *   <li>Described</li>
+ * </ul>
+ * <p>
+ * Example: A holiday on the first thursday after the second april.
+ * In this example the
+ * `first` is the which (occurrence)
+ * `thursday` is thr weekday (dayOfWeek)
+ * `after` is the when (relation)
+ * `day` is the second april (fixed)
+ * <p>
+ * The {@link de.focus_shift.jollyday.core.parser.impl.FixedWeekdayRelativeToFixedParser} is used.
+ */
 public interface FixedWeekdayRelativeToFixed extends Described, Limited {
 
+  /**
+   * Describes the anchor the new holiday
+   *
+   * @return the fixed holiday
+   */
   Fixed day();
 
+  /**
+   * Describes, based on the anchor (day), on which occurrence the new holiday will occur
+   *
+   * @return the occurrence, like the first
+   */
   Occurrence which();
 
+  /**
+   * Describes, based on the anchor (day), on which weekday the new holiday will occur
+   *
+   * @return the weekday
+   */
   DayOfWeek weekday();
 
+  /**
+   * Describes, based on the anchor (day), the relation like before, after, ... the new holiday will occur
+   *
+   * @return the relation to the anchor
+   */
   Relation when();
 
 }

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();
 
 }

jollyday-core/src/main/java/de/focus_shift/jollyday/core/spi/IslamicHoliday.java

@@ -1,15 +1,16 @@
 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>
  *   <li>Limited</li>
  *   <li>Described</li>
  * </ul>
- *
+ * <p>
  * and has a special {@link IslamicHolidayType}.
+ * <p>
  * The {@link de.focus_shift.jollyday.core.parser.impl.IslamicHolidayParser} is used.
  */
 public interface IslamicHoliday extends Described, Limited, Movable {

jollyday-core/src/main/java/de/focus_shift/jollyday/core/spi/RelativeToEasterSunday.java

@@ -4,10 +4,34 @@
 
 import java.time.chrono.Chronology;
 
+/**
+ * Represents the configuration of a holiday that is in relation to Easter Sunday and can be
+ *
+ * <ul>
+ *   <li>Limited</li>
+ *   <li>Described</li>
+ * </ul>
+ * <p>
+ * Example: A holiday 42 days after Easter Sunday.
+ * <p>
+ * The difference to {@link ChristianHoliday} is that these holidays are based on Easter Sunday but no christian holidays.
+ * <p>
+ * The {@link de.focus_shift.jollyday.core.parser.impl.RelativeToEasterSundayParser} is used.
+ */
 public interface RelativeToEasterSunday extends Described, Limited {
 
+  /**
+   * Describes the {@link Chronology} of the holiday
+   *
+   * @return the chronology of the holiday
+   */
   Chronology chronology();
 
+  /**
+   * Describes the number of days that will be added to Easter Sunday.
+   *
+   * @return the additional number of days
+   */
   Days days();
 
 }