Javadoc Clock classes; make ManualClock private[spark]

Author: srowen

core/src/main/scala/org/apache/spark/util/Clock.scala

@@ -25,12 +25,23 @@ private[spark] trait Clock {
   def waitTillTime(targetTime: Long): Long
 }
 
+/**
+ * A clock backed by the actual time from the OS as reported by the `System` API.
+ */
 private[spark] class SystemClock extends Clock {
 
   val minPollTime = 25L
 
+  /**
+   * @return the same time (milliseconds since the epoch)
+   *         as is reported by `System.currentTimeMillis()`
+   */
   def getTimeMillis(): Long = System.currentTimeMillis()
 
+  /**
+   * @param targetTime block until the current time is at least this value
+   * @return current system time when wait has completed
+   */
   def waitTillTime(targetTime: Long): Long = {
     var currentTime = 0L
     currentTime = System.currentTimeMillis()

core/src/main/scala/org/apache/spark/util/ManualClock.scala

@@ -17,27 +17,47 @@
 
 package org.apache.spark.util
 
-class ManualClock(private var time: Long) extends Clock {
+/**
+ * A `Clock` whose time can be manually set and modified. Its reported time does not change
+ * as time elapses, but only as its time is modified by callers. This is mainly useful for
+ * testing.
+ *
+ * @param time initial time (in milliseconds since the epoch)
+ */
+private[spark] class ManualClock(private var time: Long) extends Clock {
 
+  /**
+   * @return `ManualClock` with initial time 0
+   */
   def this() = this(0L)
 
   def getTimeMillis(): Long =
     synchronized {
       time
     }
 
+  /**
+   * @param timeToSet new time (in milliseconds) that the clock should represent
+   */
   def setTime(timeToSet: Long) =
     synchronized {
       time = timeToSet
       notifyAll()
     }
 
+  /**
+   * @param timeToAdd time (in milliseconds) to add to the clock's time
+   */
   def advance(timeToAdd: Long) =
-    this.synchronized {
+    synchronized {
       time += timeToAdd
       notifyAll()
     }
 
+  /**
+   * @param targetTime block until the clock time is set or advanced to at least this time
+   * @return current time reported by the clock when waiting finishes
+   */
   def waitTillTime(targetTime: Long): Long =
     synchronized {
       while (time < targetTime) {