diff --git a/user/src/com/google/web/bindery/requestfactory/shared/EntityProxyChange.java b/user/src/com/google/web/bindery/requestfactory/shared/EntityProxyChange.java
index 12cba42..c146efb 100644
--- a/user/src/com/google/web/bindery/requestfactory/shared/EntityProxyChange.java
+++ b/user/src/com/google/web/bindery/requestfactory/shared/EntityProxyChange.java
@@ -21,17 +21,19 @@
 import com.google.gwt.event.shared.HandlerRegistration;
 
 /**
- * Abstract base class for an event announcing changes to an
- * {@link EntityProxy}.
+ * Event posted by a {@link RequestFactory} when changes to an entity are
+ * detected. Provides a {@link WriteOperation} value describing the change, and
+ * the {@link EntityProxyId} of the entity in question.
  * <p>
- * Note that this event includes an unpopulated copy of the changed proxy
- * &mdash; all properties are undefined except it's id. That is, the event
- * includes only enough information for receivers to issue requests to get
- * themselves fresh copies of the proxy.
- * <p>
- * TODO: use ProxyId rather than an empty proxy
- *
+ * EntityProxyChange events are posted with the relevant EntityProxy
+ * Class as their source, allowing handlers to register for changes only
+ * of the type they care about via
+ * {@link #registerForProxyType(EventBus, Class, Handler)}.
+ * 
  * @param <P> the type of the proxy
+ * 
+ * @see RequestFactory#initialize(EventBus)
+ * @see RequestFactory#find(EntityProxyId)
  */
 public class EntityProxyChange<P extends EntityProxy> extends
     GwtEvent<EntityProxyChange.Handler<P>> {
diff --git a/user/src/com/google/web/bindery/requestfactory/shared/WriteOperation.java b/user/src/com/google/web/bindery/requestfactory/shared/WriteOperation.java
index 53a9b47..9f74a53 100644
--- a/user/src/com/google/web/bindery/requestfactory/shared/WriteOperation.java
+++ b/user/src/com/google/web/bindery/requestfactory/shared/WriteOperation.java
@@ -16,15 +16,24 @@
 package com.google.web.bindery.requestfactory.shared;
 
 /**
- * The enum used in {@link EntityProxyChange}.
- * <ul>
- * <li>A PERSIST event is fired after a proxy that was created on the client has
- * been persisted on the server.
- * <li>An UPDATE event is fired whenever a client encounters a proxy for the
- * first time, or encounters a proxy whose version number has changed.
- * <li>A DELETE event is fired after a proxy that was deleted on the client is
- * deleted on the server as well.
- * </ul>
+ * The values returned by {@link EntityProxyChange#getWriteOperation()} to
+ * describe the type of change being announced.
+ * 
+ * <dl>
+ * <dt>PERSIST
+ * <dd>An {@link EntityProxy} that was created on the client has been persisted
+ * on the server
+ * 
+ * <dt>UPDATE
+ * <dd>An {@link EntityProxy} has been encountered by the client for the first
+ * time, or its version value has changed
+ * 
+ * <dt>DELETE
+ * <dd>The server has confirmed the success of a client request to delete an
+ * {@link EntityProxy}
+ * </dl>
+ * 
+ * @see EntityProxyChange#getWriteOperation()
  */
 public enum WriteOperation {
   PERSIST("PERSIST"), UPDATE("UPDATE"), DELETE("DELETE");