HBASE-15791 Improve javadoc around ScheduledChore

hbase-common/src/main/java/org/apache/hadoop/hbase/ScheduledChore.java

@@ -55,9 +55,9 @@ public abstract class ScheduledChore implements Runnable {
   /**
    * Scheduling parameters. Used by ChoreService when scheduling the chore to run periodically
    */
-  private final int period;
+  private final int period; // in TimeUnit units
   private final TimeUnit timeUnit;
-  private final long initialDelay;
+  private final long initialDelay; // in TimeUnit units
 
   /**
    * Interface to the ChoreService that this ScheduledChore is scheduled with. null if the chore is
@@ -68,8 +68,8 @@ public abstract class ScheduledChore implements Runnable {
   /**
    * Variables that encapsulate the meaningful state information
    */
-  private long timeOfLastRun = -1;
+  private long timeOfLastRun = -1; // system time millis
-  private long timeOfThisRun = -1;
+  private long timeOfThisRun = -1; // system time millis
   private boolean initialChoreComplete = false;
 
   /**
@@ -127,7 +127,7 @@ public abstract class ScheduledChore implements Runnable {
   /**
    * @param name Name assigned to Chore. Useful for identification amongst chores of the same type
    * @param stopper When {@link Stoppable#isStopped()} is true, this chore will cancel and cleanup
-   * @param period Period with which this Chore repeats execution when scheduled.
+   * @param period Period in millis with which this Chore repeats execution when scheduled.
    */
   public ScheduledChore(final String name, Stoppable stopper, final int period) {
     this(name, stopper, period, DEFAULT_INITIAL_DELAY);
@@ -136,7 +136,7 @@ public abstract class ScheduledChore implements Runnable {
   /**
    * @param name Name assigned to Chore. Useful for identification amongst chores of the same type
    * @param stopper When {@link Stoppable#isStopped()} is true, this chore will cancel and cleanup
-   * @param period Period with which this Chore repeats execution when scheduled.
+   * @param period Period in millis with which this Chore repeats execution when scheduled.
    * @param initialDelay Delay before this Chore begins to execute once it has been scheduled. A
    *          value of 0 means the chore will begin to execute immediately. Negative delays are
    *          invalid and will be corrected to a value of 0.
@@ -149,10 +149,10 @@ public abstract class ScheduledChore implements Runnable {
   /**
    * @param name Name assigned to Chore. Useful for identification amongst chores of the same type
    * @param stopper When {@link Stoppable#isStopped()} is true, this chore will cancel and cleanup
-   * @param period Period with which this Chore repeats execution when scheduled.
+   * @param period Period in Timeunit unit with which this Chore repeats execution when scheduled.
-   * @param initialDelay Delay before this Chore begins to execute once it has been scheduled. A
+   * @param initialDelay Delay in Timeunit unit before this Chore begins to execute once it has been
-   *          value of 0 means the chore will begin to execute immediately. Negative delays are
+   *          scheduled. A value of 0 means the chore will begin to execute immediately. Negative
-   *          invalid and will be corrected to a value of 0.
+   *          delays are invalid and will be corrected to a value of 0.
    * @param unit The unit that is used to measure period and initialDelay
    */
   public ScheduledChore(final String name, Stoppable stopper, final int period,
@@ -213,8 +213,8 @@ public abstract class ScheduledChore implements Runnable {
   }
 
   /**
-   * @return How long has it been since this chore last run. Useful for checking if the chore has
+   * @return How long in millis has it been since this chore last run. Useful for checking if the
-   *         missed its scheduled start time by too large of a margin
+   *         chore has missed its scheduled start time by too large of a margin
    */
   synchronized long getTimeBetweenRuns() {
     return timeOfThisRun - timeOfLastRun;
@@ -228,11 +228,18 @@ public abstract class ScheduledChore implements Runnable {
         && getTimeBetweenRuns() > getMaximumAllowedTimeBetweenRuns();
   }
 
+  /**
+   * @return max allowed time in millis between runs.
+   */
   private double getMaximumAllowedTimeBetweenRuns() {
     // Threshold used to determine if the Chore's current run started too late
     return 1.5 * timeUnit.toMillis(period);
   }
 
+  /**
+   * @param time in system millis
+   * @return true if time is earlier or equal to current milli time
+   */
   private synchronized boolean isValidTime(final long time) {
     return time > 0 && time <= System.currentTimeMillis();
   }
@@ -276,10 +283,16 @@ public abstract class ScheduledChore implements Runnable {
     return stopper;
   }
 
+  /**
+   * @return period to execute chore in getTimeUnit() units
+   */
   public int getPeriod() {
     return period;
   }
 
+  /**
+   * @return initial delay before executing chore in getTimeUnit() units
+   */
   public long getInitialDelay() {
     return initialDelay;
   }