diff --git a/akka-cluster/src/main/scala/akka/cluster/Cluster.scala b/akka-cluster/src/main/scala/akka/cluster/Cluster.scala
index 08b362dce0..153d0a3471 100644
--- a/akka-cluster/src/main/scala/akka/cluster/Cluster.scala
+++ b/akka-cluster/src/main/scala/akka/cluster/Cluster.scala
@@ -42,13 +42,13 @@ object Cluster extends ExtensionId[Cluster] with ExtensionIdProvider {
 }
 
 /**
- * This module is responsible for Gossiping cluster information. The abstraction maintains the list of live
- * and dead members. Periodically i.e. every 1 second this module chooses a random member and initiates a round
- * of Gossip with it.
- * <p/>
- * During each round of gossip exchange it sends Gossip to random node with
- * newer or older state information, if any, based on the current gossip overview,
- * with some probability. Otherwise Gossip to any random live node.
+ * This module is responsible cluster membership information. Changes to the cluster
+ * information is retrieved through [[#subscribe]]. Commands to operate the cluster is
+ * available through methods in this class, such as [[#join]], [[#down]] and [[#leave]].
+ *
+ * Each cluster [[Member]] is identified by its [[akka.actor.Address]], and
+ * the cluster address of this actor system is [[#selfAddress]]. A member also has a status;
+ * initially [[MemberStatus.Joining]] followed by [[MemberStatus.Up]].
  */
 class Cluster(val system: ExtendedActorSystem) extends Extension {
 
@@ -260,12 +260,26 @@ class Cluster(val system: ExtendedActorSystem) extends Extension {
 
   /**
    * Send command to issue state transition to LEAVING for the node specified by 'address'.
+   * The member will go through the status changes [[MemberStatus.Leaving]] (not published to
+   * subscribers) followed by [[MemberStatus.Exiting]] and finally [[MemberStatus.Removed]].
+   *
+   * Note that this command can be issued to any member in the cluster, not necessarily the
+   * one that is leaving. The cluster extension, but not the actor system or JVM, of the
+   * leaving member will be shutdown after the leader has changed status of the member to
+   * Exiting. Thereafter the member will be removed from the cluster. Normally this is
+   * handled automatically, but in case of network failures during this process it might
+   * still be necessary to set the node’s status to Down in order to complete the removal.
    */
   def leave(address: Address): Unit =
     clusterCore ! ClusterUserAction.Leave(address)
 
   /**
    * Send command to DOWN the node specified by 'address'.
+   *
+   * When a member is considered by the failure detector to be unreachable the leader is not
+   * allowed to perform its duties, such as changing status of new joining members to 'Up'.
+   * The status of the unreachable member must be changed to 'Down', which can be done with
+   * this method.
    */
   def down(address: Address): Unit =
     clusterCore ! ClusterUserAction.Down(address)
diff --git a/akka-cluster/src/main/scala/akka/cluster/ClusterMetricsCollector.scala b/akka-cluster/src/main/scala/akka/cluster/ClusterMetricsCollector.scala
index 2546470be4..028fbd4e14 100644
--- a/akka-cluster/src/main/scala/akka/cluster/ClusterMetricsCollector.scala
+++ b/akka-cluster/src/main/scala/akka/cluster/ClusterMetricsCollector.scala
@@ -227,7 +227,7 @@ private[cluster] case class MetricsGossip(nodes: Set[NodeMetrics]) {
 private[cluster] case class MetricsGossipEnvelope(from: Address, gossip: MetricsGossip, reply: Boolean)
   extends ClusterMessage
 
-object EWMA {
+private[cluster] object EWMA {
   /**
    * math.log(2)
    */
@@ -688,8 +688,6 @@ class JmxMetricsCollector(address: Address, decayFactor: Double) extends Metrics
  * The constructor will by design throw exception if org.hyperic.sigar.Sigar can't be loaded, due
  * to missing classes or native libraries.
  *
- * TODO switch to Scala reflection
- *
  * @param address The [[akka.actor.Address]] of the node being sampled
  * @param decay how quickly the exponential weighting of past data is decayed
  * @param sigar the org.hyperic.Sigar instance
diff --git a/akka-cluster/src/main/scala/akka/cluster/protobuf/ClusterMessageSerializer.scala b/akka-cluster/src/main/scala/akka/cluster/protobuf/ClusterMessageSerializer.scala
index 529ae5595e..a56d61e41c 100644
--- a/akka-cluster/src/main/scala/akka/cluster/protobuf/ClusterMessageSerializer.scala
+++ b/akka-cluster/src/main/scala/akka/cluster/protobuf/ClusterMessageSerializer.scala
@@ -19,6 +19,9 @@ import java.util.zip.GZIPInputStream
 import com.google.protobuf.MessageLite
 import scala.annotation.tailrec
 
+/**
+ * Protobuf serializer of cluster messages.
+ */
 class ClusterMessageSerializer(val system: ExtendedActorSystem) extends Serializer {
 
   private final val BufferSize = 1024 * 4
diff --git a/akka-cluster/src/main/scala/akka/cluster/routing/AdaptiveLoadBalancingRouter.scala b/akka-cluster/src/main/scala/akka/cluster/routing/AdaptiveLoadBalancingRouter.scala
index 3c7076c2ab..4910dbdb0a 100644
--- a/akka-cluster/src/main/scala/akka/cluster/routing/AdaptiveLoadBalancingRouter.scala
+++ b/akka-cluster/src/main/scala/akka/cluster/routing/AdaptiveLoadBalancingRouter.scala
@@ -35,7 +35,7 @@ object AdaptiveLoadBalancingRouter {
  * A Router that performs load balancing of messages to cluster nodes based on
  * cluster metric data.
  *
- * It uses random selection of routees based probabilities derived from
+ * It uses random selection of routees based on probabilities derived from
  * the remaining capacity of corresponding node.
  *
  * Please note that providing both 'nrOfInstances' and 'routees' does not make logical
@@ -48,14 +48,17 @@ object AdaptiveLoadBalancingRouter {
  *
  * <h1>Supervision Setup</h1>
  *
- * The router creates a “head” actor which supervises and/or monitors the
- * routees. Instances are created as children of this actor, hence the
- * children are not supervised by the parent of the router. Common choices are
- * to always escalate (meaning that fault handling is always applied to all
- * children simultaneously; this is the default) or use the parent’s strategy,
- * which will result in routed children being treated individually, but it is
- * possible as well to use Routers to give different supervisor strategies to
- * different groups of children.
+ * Any routees that are created by a router will be created as the router's children.
+ * The router is therefore also the children's supervisor.
+ *
+ * The supervision strategy of the router actor can be configured with
+ * [[#withSupervisorStrategy]]. If no strategy is provided, routers default to
+ * a strategy of “always escalate”. This means that errors are passed up to the
+ * router's supervisor for handling.
+ *
+ * The router's supervisor will treat the error as an error with the router itself.
+ * Therefore a directive to stop or restart will cause the router itself to stop or
+ * restart. The router, in turn, will cause its children to stop and restart.
  *
  * @param metricsSelector decides what probability to use for selecting a routee, based
  *   on remaining capacity as indicated by the node metrics