diff --git a/cake/libs/cake_request.php b/cake/libs/cake_request.php
index 580f51296..23c925883 100644
--- a/cake/libs/cake_request.php
+++ b/cake/libs/cake_request.php
@@ -519,7 +519,8 @@ class CakeRequest implements ArrayAccess {
 	}
 
 /**
- * Add parameters to the request's parsed parameter set. This will overwrite any existing parameters
+ * Add parameters to the request's parsed parameter set. This will overwrite any existing parameters.
+ * This modifies the parameters available through `$request->params`.
  *
  * @param array $params Array of parameters to merge in
  * @return The current object, you can chain this method.
@@ -531,6 +532,7 @@ class CakeRequest implements ArrayAccess {
 
 /**
  * Add paths to the requests' paths vars.  This will overwrite any existing paths.
+ * Provides an easy way to modify, here, webroot and base.
  *
  * @param array $paths Array of paths to merge in
  * @return the current object, you can chain this method.
@@ -605,11 +607,11 @@ class CakeRequest implements ArrayAccess {
  *
  * #### Get all types:
  *
- * `$request->accepts();`
+ * `$this->request->accepts();`
  *
  * #### Check for a single type:
  *
- * `$request->accepts('json');`
+ * `$this->request->accepts('json');`
  *
  * @param string $type The content type to check for.  Leave null to get all types a client accepts.
  * @return mixed Either an array of all the types the client accepts or a boolean if they accept the
@@ -632,6 +634,14 @@ class CakeRequest implements ArrayAccess {
 /**
  * Get the lanaguages accepted by the client, or check if a specific language is accepted.
  *
+ * Get the list of accepted languages:
+ *
+ * {{{ CakeRequest::acceptLanguage(); }}}
+ *
+ * Check if a specific language is accepted:
+ *
+ * {{{ CakeRequest::acceptLanguage('es-es'); }}}
+ *
  * @param string $language The language to test.
  * @return If a $language is provided, a boolean. Otherwise the array of accepted languages.
  */
diff --git a/cake/libs/cake_response.php b/cake/libs/cake_response.php
index 6c3d751c2..df2ab71a0 100644
--- a/cake/libs/cake_response.php
+++ b/cake/libs/cake_response.php
@@ -1,9 +1,6 @@
 <?php
 /**
- * CakeResponse is responsible for managing the response text, status and headers of a HTTP response.
- * 
- * By default controllers will use this class to render their response. If you are going to use 
- * a custom response class it should subclass this object in order to ensure compatibility.
+ * CakeResponse 
  *
  * PHP 5
  *
@@ -20,6 +17,14 @@
  * @since         CakePHP(tm) v 2.0
  * @license       MIT License (http://www.opensource.org/licenses/mit-license.php)
  */
+/**
+ * CakeResponse is responsible for managing the response text, status and headers of a HTTP response.
+ * 
+ * By default controllers will use this class to render their response. If you are going to use 
+ * a custom response class it should subclass this object in order to ensure compatibility.
+ *
+ * @package cake.libs
+ */
 class CakeResponse {
 
 /**
@@ -501,15 +506,19 @@ class CakeResponse {
  * if $contentType is an associative array, it will be stored as a content type definition
  *
  * ### Setting the content type
+ *
  * e.g `type('jpg');`
  *
  * ### Returning the current content type
+ *
  * e.g `type();`
  *
  * ### Storing a content type definition
+ *
  * e.g `type(array('keynote' => 'application/keynote'));`
  *
  * ### Replacing a content type definition
+ *
  * e.g `type(array('jpg' => 'text/plain'));`
  *
  * @param string $contentType
@@ -624,7 +633,8 @@ class CakeResponse {
 	}
 
 /**
- * Sets the correct output buffering handler to send a compressed response
+ * Sets the correct output buffering handler to send a compressed response. Responses will
+ * be compressed with zlib, if the extension is available.
  *
  * @return boolean false if client does not accept compressed responses or no handler is available, true otherwise
  */
@@ -636,7 +646,7 @@ class CakeResponse {
 	}
 
 /**
- * Sets the correct headers to instruct the browser to dowload the response as a file
+ * Sets the correct headers to instruct the browser to dowload the response as a file.
  *
  * @param string $filename the name of the file as the browser will download the response
  * @return void