From a2186c412a3c8b2056ae2206cd121f3d15c8e0f3 Mon Sep 17 00:00:00 2001
From: mark_story <mark@mark-story.com>
Date: Sat, 28 Aug 2010 00:59:07 -0400
Subject: [PATCH] Updating doc blocks for CakeRequest and CakeResponse.

---
 cake/libs/cake_request.php  | 18 ++++++++++++++----
 cake/libs/cake_response.php | 19 ++++++++++++-------
 2 files changed, 26 insertions(+), 11 deletions(-)

diff --git a/cake/libs/cake_request.php b/cake/libs/cake_request.php
index d3828e15be5..26c769a00fb 100644
--- a/cake/libs/cake_request.php
+++ b/cake/libs/cake_request.php
@@ -3,7 +3,7 @@
  * A class that helps wrap Request information and particulars about a single request.
  * Provides methods commonly used to introspect on the request headers and request body.
  * 
- * Has both an Array and Object interface. You can access framework parameters using indexes
+ * Has both an Array and Object interface. You can access framework parameters using indexes:
  *
  * `$request['controller']` or `$request->controller`.
  *
@@ -428,6 +428,8 @@ public function __call($name, $params) {
 /**
  * Magic get method allows access to parsed routing parameters directly on the object.
  *
+ * Allows access to `$this->params['controller']` via `$this->controller`
+ *
  * @param string $name The property being accessed.
  * @return mixed Either the value of the parameter or null.
  */
@@ -441,7 +443,7 @@ public function __get($name) {
 /**
  * Check whether or not a Request is a certain type.  Uses the built in detection rules
  * as well as additional rules defined with CakeRequest::addDetector().  Any detector can be called 
- * with `is($type)` or `is$Type()`.
+ * as `is($type)` or `is$Type()`.
  *
  * @param string $type The type of request you want to check.
  * @return boolean Whether or not the request is the type you are checking.
@@ -513,7 +515,7 @@ public function addDetector($name, $options) {
 	}
 
 /**
- * Add parameters to the request's parsed parameter set.
+ * Add parameters to the request's parsed parameter set. This will overwrite any existing parameters
  *
  * @param array $params Array of parameters to merge in
  * @return The current object, you can chain this method.
@@ -524,7 +526,7 @@ public function addParams($params) {
 	}
 
 /**
- * Add paths to the requests' paths vars
+ * Add paths to the requests' paths vars.  This will overwrite any existing paths.
  *
  * @param array $paths Array of paths to merge in
  * @return the current object, you can chain this method.
@@ -597,6 +599,14 @@ function subdomains($tldLength = 1) {
  * Find out which content types the client accepts or check if they accept a 
  * particular type of content.
  *
+ * #### Get all types:
+ *
+ * `$request->accepts();`
+ *
+ * #### Check for a single type:
+ *
+ * `$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
  *   provided type.
diff --git a/cake/libs/cake_response.php b/cake/libs/cake_response.php
index acd68158e1d..b68aa65d353 100644
--- a/cake/libs/cake_response.php
+++ b/cake/libs/cake_response.php
@@ -1,7 +1,9 @@
 <?php
 /**
- * A class reposible for managing the response text, status and headers of a HTTP response
+ * 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.
  *
  * PHP 5
  *
@@ -18,7 +20,6 @@
  * @since         CakePHP(tm) v 2.0
  * @license       MIT License (http://www.opensource.org/licenses/mit-license.php)
  */
-
 class CakeResponse {
 
 /**
@@ -330,8 +331,10 @@ public function __construct(array $options = array()) {
 	}
 
 /**
-* Sends the complete response to the client including headers and message body
+* Sends the complete response to the client including headers and message body.
+* Will echo out the content in the response body.
 *
+* @return void
 */
 	public function send() {
 		if (isset($this->_headers['Location']) && $this->_status === 200) {
@@ -349,10 +352,11 @@ public function send() {
 	}
 
 /**
-* Sends a header to the client
+* Sends a header to the client.
 *
 * @param $name the header name
 * @param $value the header value
+* @return void
 */
 	protected function _sendHeader($name, $value = null) {
 		if (is_null($value)) {
@@ -363,9 +367,10 @@ protected function _sendHeader($name, $value = null) {
 	}
 
 /**
-* Sends a content string to the client
+* Sends a content string to the client.
 *
 * @param $content string to send as response body
+* @return void
 */
 	protected function _sendContent($content) {
 		echo $content;
@@ -584,7 +589,7 @@ public function charset($charset = null) {
 	}
 
 /**
- * Sets the correct headers to instruct the client to not cache te response
+ * Sets the correct headers to instruct the client to not cache the response
  *
  * @return void
  */
@@ -598,7 +603,7 @@ public function disableCache() {
 	}
 
 /**
- * Sets the correct headers to instruct the client to cache the response
+ * Sets the correct headers to instruct the client to cache the response.
  *
  * @param string $since a valid time since the response text has not been modified
  * @param string $time a valid time for cache expiry