From 1e82a231c9afd22a758b858d534981eccd6a280d Mon Sep 17 00:00:00 2001
From: Patrik Nordwall <patrik.nordwall@gmail.com>
Date: Mon, 21 May 2012 07:46:48 +0200
Subject: [PATCH] Incorporate review feedback. See #2061

---
 .../akka/docs/actor/mailbox/DurableMailboxDocSpec.scala   | 8 +++++++-
 akka-docs/modules/durable-mailbox.rst                     | 7 ++++---
 2 files changed, 11 insertions(+), 4 deletions(-)

diff --git a/akka-docs/modules/code/akka/docs/actor/mailbox/DurableMailboxDocSpec.scala b/akka-docs/modules/code/akka/docs/actor/mailbox/DurableMailboxDocSpec.scala
index 25f312cac3..c81f16e896 100644
--- a/akka-docs/modules/code/akka/docs/actor/mailbox/DurableMailboxDocSpec.scala
+++ b/akka-docs/modules/code/akka/docs/actor/mailbox/DurableMailboxDocSpec.scala
@@ -73,13 +73,19 @@ class MyMessageQueue(_owner: ActorContext)
 
   def dequeue(): Envelope = {
     val data: Option[Array[Byte]] = storage.pull()
-    data.map(deserialize(_)).getOrElse(null)
+    data.map(deserialize).orNull
   }
 
   def hasMessages: Boolean = !storage.isEmpty
 
   def numberOfMessages: Int = storage.size
 
+  /**
+   * Called when the mailbox is disposed.
+   * An ordinary mailbox would send remaining messages to deadLetters,
+   * but the purpose of a durable mailbox is to continue
+   * with the same message queue when the actor is started again.
+   */
   def cleanUp(owner: ActorContext, deadLetters: MessageQueue): Unit = ()
 
 }
diff --git a/akka-docs/modules/durable-mailbox.rst b/akka-docs/modules/durable-mailbox.rst
index 4de60ea12b..aca9d51eb5 100644
--- a/akka-docs/modules/durable-mailbox.rst
+++ b/akka-docs/modules/durable-mailbox.rst
@@ -9,7 +9,7 @@
 Overview
 ========
 
-A durable mailbox is a replacement for the standard actor mailbox that is durable.
+A durable mailbox is a mailbox which stores the messages on durable storage.
 What this means in practice is that if there are pending messages in the actor's
 mailbox when the node of the actor resides on crashes, then when you restart the
 node, the actor will be able to continue processing as if nothing had happened;
@@ -29,7 +29,7 @@ Open Source projects, such as:
 * `AMQP Durable Mailbox <https://github.com/drexin/akka-amqp-mailbox>`_
 
 
-A durable mailbox typically doesn't implements transactions for current message. It's possible
+A durable mailbox is like any other mailbox not likely to be transactional. It's possible
 if the actor crashes after receiving a message, but before completing processing of
 it, that the message could be lost.
 
@@ -98,4 +98,5 @@ Add this dependency::
   "com.typesafe.akka" % "akka-mailboxes-common-test" % "2.1-SNAPSHOT"
 
 For more inspiration you can look at the old implementations based on Redis, MongoDB, Beanstalk,
-and ZooKeeper, which can be found in Akka git repository tag v2.0.1.
\ No newline at end of file
+and ZooKeeper, which can be found in Akka git repository tag
+`v2.0.1 <https://github.com/akka/akka/tree/v2.0.1/akka-durable-mailboxes>`_.
\ No newline at end of file