diff --git a/modules/cpr/src/main/java/org/atmosphere/cpr/AtmosphereRequest.java b/modules/cpr/src/main/java/org/atmosphere/cpr/AtmosphereRequest.java
index c4476d5940b..ac22fb0b6e3 100644
--- a/modules/cpr/src/main/java/org/atmosphere/cpr/AtmosphereRequest.java
+++ b/modules/cpr/src/main/java/org/atmosphere/cpr/AtmosphereRequest.java
@@ -50,7 +50,14 @@
 import static org.atmosphere.cpr.HeaderConfig.X_ATMOSPHERE;
 
 /**
- * An Atmosphere request representation.
+ * An Atmosphere request representation. An {@link AtmosphereRequest} is a two-way communication channel between the
+ * client and the server. If the {@link org.atmosphere.cpr.AtmosphereRequest#isDestroyable()} is set to false, or if its
+ * associated {@link AtmosphereResource} has been suspended, this object can be re-used at any moments between requests.
+ * You can use it's associated {@link AtmosphereResponse} to write bytes at any moment, making this object bi-directional.
+ * <br/>
+ * You can retrieve the AtmosphereResource can be retrieved as an attribute {@link FrameworkConfig#ATMOSPHERE_RESOURCE}.
+ *
+ * @author Jeanfrancois Arcand
  */
 public class AtmosphereRequest extends HttpServletRequestWrapper {
 
@@ -1003,6 +1010,11 @@ public AsyncContext startAsync(ServletRequest request, ServletResponse response)
         }
     }
 
+    /**
+     * Wrap an {@link HttpServletRequest}.
+     * @param request {@link HttpServletRequest}
+     * @return an {@link AtmosphereRequest}
+     */
     public final static AtmosphereRequest wrap(HttpServletRequest request) {
         return new Builder().request(request).build();
     }
diff --git a/modules/cpr/src/main/java/org/atmosphere/cpr/AtmosphereResponse.java b/modules/cpr/src/main/java/org/atmosphere/cpr/AtmosphereResponse.java
index 5eead2dcf97..414c78eb49c 100644
--- a/modules/cpr/src/main/java/org/atmosphere/cpr/AtmosphereResponse.java
+++ b/modules/cpr/src/main/java/org/atmosphere/cpr/AtmosphereResponse.java
@@ -32,8 +32,15 @@
 import java.util.concurrent.atomic.AtomicBoolean;
 
 /**
- * Wrapper around an {@link HttpServletResponse} which use an instance of {@link org.atmosphere.websocket.WebSocket}
- * as a writer.
+ * An Atmosphere's response representation. An AtmosphereResponse can be used to construct bi-directional asynchronous
+ * application. If the underlying transport is a WebSocket or if its associated {@link AtmosphereResource} has been
+ * suspended, this object can be used to write message back tp the client at any moment.
+ * <br/>
+ * This object can delegates the write operation to {@link AsyncIOWriter}. An {@link AsyncProtocol} can also be
+ * consulted before the bytes/string write process gets delegated to an {@link AsyncIOWriter}. If {@link org.atmosphere.cpr.AsyncProtocol#inspectResponse()}
+ * return true, the {@link org.atmosphere.cpr.AsyncProtocol#handleResponse(AtmosphereResponse, String)} will have a chance to
+ * manipulate the bytes and return a new representation. That new representation will then be delegated to an
+ * {@link AsyncIOWriter}.
  */
 public class AtmosphereResponse extends HttpServletResponseWrapper {
 
@@ -803,6 +810,11 @@ public byte[] handleResponse(AtmosphereResponse res, byte[] message, int offset,
         }
     }
 
+    /**
+     * Wrap an {@link HttpServletResponse}
+     * @param response  {@link HttpServletResponse}
+     * @return  an {@link AtmosphereResponse}
+     */
     public final static AtmosphereResponse wrap(HttpServletResponse response) {
         return new Builder().response(response).build();
     }