Updated the scheduler implementation after feedback; changed Duration(x, timeunit) to more fluent 'x timeunit' and added ScalaDoc

akka-actor/src/main/scala/akka/actor/Scheduler.scala

@@ -15,14 +15,44 @@ package akka.actor
 import akka.util.Duration
 
 trait Scheduler {
-  def schedule(receiver: ActorRef, message: Any, initialDelay: Duration, delay: Duration): Cancellable
-  def schedule(f: () ⇒ Unit, initialDelay: Duration, delay: Duration): Cancellable
+  /**
+   * Schedules a message to be sent repeatedly with an initial delay and frequency.
+   * E.g. if you would like a message to be sent immediately and thereafter every 500ms you would set
+   * delay = Duration.Zero and frequency = Duration(500, TimeUnit.MILLISECONDS)
+   */
+  def schedule(receiver: ActorRef, message: Any, initialDelay: Duration, frequency: Duration): Cancellable
+
+  /**
+   * Schedules a function to be run repeatedly with an initial delay and a frequency.
+   * E.g. if you would like the function to be run after 2 seconds and thereafter every 100ms you would set
+   * delay = Duration(2, TimeUnit.SECONDS) and frequency = Duration(100, TimeUnit.MILLISECONDS)
+   */
+  def schedule(f: () ⇒ Unit, initialDelay: Duration, frequency: Duration): Cancellable
+
+  /**
+   * Schedules a Runnable to be run once with a delay, i.e. a time period that has to pass before the runnable is executed.
+   */
   def scheduleOnce(runnable: Runnable, delay: Duration): Cancellable
+
+  /**
+   * Schedules a message to be sent once with a delay, i.e. a time period that has to pass before the message is sent.
+   */
   def scheduleOnce(receiver: ActorRef, message: Any, delay: Duration): Cancellable
+
+  /**
+   * Schedules a function to be run once with a delay, i.e. a time period that has to pass before the function is run.
+   */
   def scheduleOnce(f: () ⇒ Unit, delay: Duration): Cancellable
 }
 
 trait Cancellable {
+  /**
+   * Cancels the underlying scheduled task.
+   */
   def cancel(): Unit
+
+  /**
+   * Checks if the underlying scheduled task has been cancelled.
+   */
   def isCancelled: Boolean
 }