diff --git a/akka-actor/src/main/scala/akka/actor/Actor.scala b/akka-actor/src/main/scala/akka/actor/Actor.scala
index 9adff5594e..e7337924fd 100644
--- a/akka-actor/src/main/scala/akka/actor/Actor.scala
+++ b/akka-actor/src/main/scala/akka/actor/Actor.scala
@@ -246,6 +246,8 @@ trait Actor {
 
   /**
    * User overridable callback: '''By default it disposes of all children and then calls `postStop()`.'''
+   * @param reason the Throwable that caused the restart to happen
+   * @param message optionally the current message the actor processed when failing, if applicable
    * <p/>
    * Is called on a crashed Actor right BEFORE it is restarted to allow clean
    * up of resources before Actor is terminated.
@@ -257,6 +259,7 @@ trait Actor {
 
   /**
    * User overridable callback: By default it calls `preStart()`.
+   * @param reason the Throwable that caused the restart to happen
    * <p/>
    * Is called right AFTER restart on the newly created Actor to allow reinitialization after an Actor crash.
    */
diff --git a/akka-actor/src/main/scala/akka/actor/TypedActor.scala b/akka-actor/src/main/scala/akka/actor/TypedActor.scala
index 279876af7b..319bd10a50 100644
--- a/akka-actor/src/main/scala/akka/actor/TypedActor.scala
+++ b/akka-actor/src/main/scala/akka/actor/TypedActor.scala
@@ -340,21 +340,23 @@ object TypedActor extends ExtensionId[TypedActorExtension] with ExtensionIdProvi
    */
   trait PreRestart {
     /**
-     * User overridable callback.
+     * User overridable callback: '''By default it disposes of all children and then calls `postStop()`.'''
+     * @param reason the Throwable that caused the restart to happen
+     * @param message optionally the current message the actor processed when failing, if applicable
      * <p/>
      * Is called on a crashed Actor right BEFORE it is restarted to allow clean
      * up of resources before Actor is terminated.
-     * By default it calls postStop()
+     * By default it terminates all children and calls postStop()
      */
     def preRestart(reason: Throwable, message: Option[Any]): Unit
   }
 
   trait PostRestart {
     /**
-     * User overridable callback.
+     * User overridable callback: By default it calls `preStart()`.
+     * @param reason the Throwable that caused the restart to happen
      * <p/>
      * Is called right AFTER restart on the newly created Actor to allow reinitialization after an Actor crash.
-     * By default it calls preStart()
      */
     def postRestart(reason: Throwable): Unit
   }