diff --git a/spring-cloud-commons/src/main/java/org/springframework/cloud/client/discovery/event/HeartbeatEvent.java b/spring-cloud-commons/src/main/java/org/springframework/cloud/client/discovery/event/HeartbeatEvent.java
index 3e6e0c7a..040c4646 100644
--- a/spring-cloud-commons/src/main/java/org/springframework/cloud/client/discovery/event/HeartbeatEvent.java
+++ b/spring-cloud-commons/src/main/java/org/springframework/cloud/client/discovery/event/HeartbeatEvent.java
@@ -19,22 +19,41 @@ package org.springframework.cloud.client.discovery.event;
 import org.springframework.context.ApplicationEvent;
 
 /**
- * Event DiscoveryClient implementation can broadcast if they support
- * heartbeat's from the discovery server
+ * Event DiscoveryClient implementation can broadcast if they support heartbeat's from the
+ * discovery server. Provides listeners with a basic indication of a state change in the
+ * service catalog.
+ *
  * @author Spencer Gibb
+ * @author Dave Syer
  */
 @SuppressWarnings("serial")
 public class HeartbeatEvent extends ApplicationEvent {
 
-	private final Object value;
+	private final Object state;
 
-	public HeartbeatEvent(Object source, Object value) {
+	/**
+	 * Create a new event with a source (for example a discovery client) and a value.
+	 * Neither parameter should be relied on to have specific content or format.
+	 *
+	 * @param source the source of the event
+	 * @param state the value indicating state of the catalog
+	 */
+	public HeartbeatEvent(Object source, Object state) {
 		super(source);
-		this.value = value;
+		this.state = state;
 	}
 
+	/**
+	 * A value representing the state of the service catalog. The only requirement is that
+	 * it changes when the catalog is updated, so it can be as simple as a version
+	 * conuter, or a hash. Implementations can provide information to help users visualize
+	 * what is going on in the catalog, but users should not rely on the content (since
+	 * the implementation of the underlying discovery might change).
+	 *
+	 * @return A value representing state of the service catalog
+	 */
 	public Object getValue() {
-		return this.value;
+		return this.state;
 	}
 
 }
diff --git a/spring-cloud-commons/src/main/java/org/springframework/cloud/client/discovery/event/HeartbeatMonitor.java b/spring-cloud-commons/src/main/java/org/springframework/cloud/client/discovery/event/HeartbeatMonitor.java
index 1eaf78ee..c5dc1155 100644
--- a/spring-cloud-commons/src/main/java/org/springframework/cloud/client/discovery/event/HeartbeatMonitor.java
+++ b/spring-cloud-commons/src/main/java/org/springframework/cloud/client/discovery/event/HeartbeatMonitor.java
@@ -19,6 +19,9 @@ package org.springframework.cloud.client.discovery.event;
 import java.util.concurrent.atomic.AtomicReference;
 
 /**
+ * Helper class for listeners to the {@link HeartbeatEvent} providing a convenient way to
+ * determine if there has been a change in state.
+ *
  * @author Dave Syer
  */
 public class HeartbeatMonitor {
diff --git a/spring-cloud-commons/src/main/java/org/springframework/cloud/client/discovery/event/ParentHeartbeatEvent.java b/spring-cloud-commons/src/main/java/org/springframework/cloud/client/discovery/event/ParentHeartbeatEvent.java
index 44914908..5633e1e0 100644
--- a/spring-cloud-commons/src/main/java/org/springframework/cloud/client/discovery/event/ParentHeartbeatEvent.java
+++ b/spring-cloud-commons/src/main/java/org/springframework/cloud/client/discovery/event/ParentHeartbeatEvent.java
@@ -19,13 +19,16 @@ package org.springframework.cloud.client.discovery.event;
 import org.springframework.context.ApplicationEvent;
 
 /**
- * Heartbeat Event that a Parent ApplicationContext can send to a child Context. Useful
- * when config server is located via DiscoveryClient
+ * Heartbeat Event that a Parent ApplicationContext can send to a child Context. Useful,
+ * for example, when config server is located via DiscoveryClient, in which case the
+ * {@link HeartbeatEvent} that triggers this event is fired in the parent (bootstrap)
+ * context.
+ *
  * @author Spencer Gibb
  */
 @SuppressWarnings("serial")
-//WARNING: do not extend HearbeatEvent because of a parent context forwarding
-//Heartbeat events to a child.  Avoids a stack overflow.
+// WARNING: do not extend HearbeatEvent because of a parent context forwarding
+// Heartbeat events to a child. Avoids a stack overflow.
 public class ParentHeartbeatEvent extends ApplicationEvent {
 
 	private final Object value;