[JENKINS-41864] More Javadoc, rephrase warning message

core/src/main/java/hudson/scheduler/CronTab.java

@@ -326,6 +326,9 @@ public final class CronTab {
      * See {@link #ceil(long)}.
      *
      * This method modifies the given calendar and returns the same object.
+     *
+     * @throws RareOrImpossibleDateException if the date isn't hit in the 2 years after it indicates an impossible
+     * (e.g. Jun 31) date, or at least a date too rare to be useful. This addresses JENKINS-41864 and was added in TODO
      */
     public Calendar ceil(Calendar cal) {
         Calendar twoYearsFuture = (Calendar) cal.clone();
@@ -333,7 +336,7 @@ public final class CronTab {
         OUTER:
         while (true) {
             if (cal.compareTo(twoYearsFuture) > 0) {
-                // we went at least two years into the future
+                // we went too far into the future
                 throw new RareOrImpossibleDateException();
             }
             for (CalendarField f : CalendarField.ADJUST_ORDER) {
@@ -384,6 +387,9 @@ public final class CronTab {
      * See {@link #floor(long)}
      *
      * This method modifies the given calendar and returns the same object.
+     *
+     * @throws RareOrImpossibleDateException if the date isn't hit in the 2 years before it indicates an impossible
+     * (e.g. Jun 31) date, or at least a date too rare to be useful. This addresses JENKINS-41864 and was added in TODO
      */
     public Calendar floor(Calendar cal) {
         Calendar twoYearsAgo = (Calendar) cal.clone();
@@ -392,7 +398,7 @@ public final class CronTab {
         OUTER:
         while (true) {
             if (cal.compareTo(twoYearsAgo) < 0) {
-                // we went at least two years into the past
+                // we went too far into the past
                 throw new RareOrImpossibleDateException();
             }
             for (CalendarField f : CalendarField.ADJUST_ORDER) {

core/src/main/java/hudson/scheduler/RareOrImpossibleDateException.java

@@ -26,6 +26,28 @@ package hudson.scheduler;
 import org.kohsuke.accmod.Restricted;
 import org.kohsuke.accmod.restrictions.NoExternalUse;
 
+import java.util.Calendar;
+
+/**
+ * This exception is thrown when trying to determine the previous or next occurrence of a given date determines
+ * that it's not happened, or going to happen, within some time period (e.g. within the next year).
+ *
+ * <p>This can typically have a few different reasons:</p>
+ *
+ * <ul>
+ *   <li>The date is impossible. For example, June 31 does never happen, so <tt>0 0 31 6 *</tt> will never happen</li>
+ *   <li>The date happens only rarely
+ *     <ul>
+ *       <li>February 29 being the obvious one</li>
+ *       <li>Cron tab patterns specifying all of month, day of month, and day of week can also occur so rarely to trigger this exception</li>
+ *     </ul>
+ *   </li>
+ * </ul>
+ *
+ * @see CronTab#floor(Calendar)
+ * @see CronTab#ceil(Calendar)
+ * @since TODO
+ */
 @Restricted(NoExternalUse.class)
 public class RareOrImpossibleDateException extends RuntimeException {
 }

core/src/main/resources/hudson/triggers/Messages.properties

@@ -29,7 +29,7 @@ TimerTrigger.MissingWhitespace=You appear to be missing whitespace between * and
 TimerTrigger.no_schedules_so_will_never_run=No schedules so will never run
 TimerTrigger.TimerTriggerCause.ShortDescription=Started by timer
 TimerTrigger.would_last_have_run_at_would_next_run_at=Would last have run at {0}; would next run at {1}.
-TimerTrigger.the_specified_cron_tab_is_rare_or_impossible=This cron tab will match dates only rarely (e.g. February 29) or \
+TimerTrigger.the_specified_cron_tab_is_rare_or_impossible=This schedule will match dates only rarely (e.g. February 29) or \
   never (e.g. June 31), so this job may be triggered very rarely, if at all.
 Trigger.init=Initializing timer for triggers
 SCMTrigger.AdministrativeMonitorImpl.DisplayName=Too Many SCM Polling Threads