Add more documentation.

lib/Cake/Network/Http/Adapter/Stream.php

@@ -202,10 +202,11 @@ protected function _buildSslContext(Request $request, $options) {
 /**
  * Open the stream and send the request.
  *
- * @return void
+ * @param Request $request
+ * @return Response The populated response object.
  * @throws Cake\Error\Exception
  */
-	protected function _send($request) {
+	protected function _send(Request $request) {
 		$url = $request->url();
 		$this->_open($url);
 		$content = '';
@@ -255,7 +256,9 @@ protected function _connectionErrorHandler($code, $message) {
 	}
 
 /**
- * Get the contextOptions.
+ * Get the context options
+ *
+ * Useful for debugging and testing context creation.
  *
  * @return array
  */

lib/Cake/Network/Http/Client.php

@@ -25,8 +25,21 @@
  *
  * ### Scoped clients
  *
+ * If you're doing multiple requests to the same hostname its often convienent
+ * to use the constructor arguments to create a scoped client. This allows you
+ * to keep your code DRY and not repeat hostnames, authentication, and other options.
+ *
  * ### Doing requests
  *
+ * Once you've created an instance of Client you can do requests
+ * using several methods. Each corresponds to a different HTTP method.
+ *
+ * - get()
+ * - post()
+ * - put()
+ * - delete()
+ * - patch()
+ *
  * ### Sending request bodies
  *
  * By default any POST/PUT/PATCH/DELETE request with $data will
@@ -44,9 +57,23 @@
  *
  * ### Using authentication
  *
+ * By using the `auth` key you can use authentication. The type sub option
+ * can be used to specify which authentication strategy you want to use.
+ * CakePHP comes with a few built-in strategies:
+ *
+ * - Basic
+ * - Digest
+ * - Oauth
  *
  * ### Using proxies
  *
+ * By using the `proxy` key you can set authentication credentials for
+ * a proxy if you need to use one.. The type sub option can be used to 
+ * specify which authentication strategy you want to use.
+ * CakePHP comes with a few built-in strategies:
+ *
+ * - Basic
+ * - Digest
  *
  */
 class Client {
@@ -80,6 +107,19 @@ class Client {
  *
  * ### Config options
  *
+ * You can set the following options when creating a client:
+ *
+ * - host - The hostname to do requests on.
+ * - port - The port to use.
+ * - scheme - The default scheme/protocol to use. Defaults to http.
+ * - timeout - The timeout in seconds. Defaults to 30
+ * - ssl_verify_peer - Whether or not SSL certificates should be validated.
+ *   Defaults to true.
+ * - ssl_verify_depth - The maximum certificate chain depth to travers.
+ *   Defaults to 5.
+ * - ssl_verify_host - Verify that the certificate and hostname match.
+ *   Defaults to true.
+ * - redirect - Number of redirects to follow. Defaults to false.
  *
  * @param array $config Config options for scoped clients.
  */

lib/Cake/Network/Http/Message.php

@@ -24,6 +24,10 @@ class Message {
 	const STATUS_OK = 200;
 	const STATUS_CREATED = 201;
 	const STATUS_ACCEPTED = 202;
+	const STATUS_MOVED_PERMANENTLY = 301;
+	const STATUS_FOUND = 302;
+	const STATUS_SEE_OTHER = 303;
+	const STATUS_TEMPORARY_REDIRECT = 307;
 
 	const METHOD_GET = 'GET';
 	const METHOD_POST = 'POST';

lib/Cake/Network/Http/Request.php

@@ -24,10 +24,25 @@
  */
 class Request extends Message {
 
-	protected $_method;
+/**
+ * The HTTP method to use.
+ *
+ * @var string
+ */
+	protected $_method = self::METHOD_GET;
 
+/**
+ * Request body to send.
+ *
+ * @var mixed
+ */
 	protected $_body;
 
+/**
+ * The URL to request.
+ *
+ * @var string
+ */
 	protected $_url;
 
 /**

lib/Cake/Network/Http/Response.php

@@ -173,10 +173,12 @@ protected function _parseCookie($value) {
  * @return boolean
  */
 	public function isOk() {
-		return in_array(
-			$this->_code,
-			[static::STATUS_OK, static::STATUS_CREATED, static::STATUS_ACCEPTED]
-		);
+		$codes = [
+			static::STATUS_OK,
+			static::STATUS_CREATED,
+			static::STATUS_ACCEPTED
+		];
+		return in_array($this->_code, $codes);
 	}
 
 /**
@@ -185,8 +187,14 @@ public function isOk() {
  * @return boolean
  */
 	public function isRedirect() {
+		$codes = [
+			static::STATUS_MOVED_PERMANENTLY,
+			static::STATUS_FOUND,
+			static::STATUS_SEE_OTHER,
+			static::STATUS_TEMPORARY_REDIRECT,
+		];
 		return (
-			in_array($this->_code, array(301, 302, 303, 307)) &&
+			in_array($this->_code, $codes) &&
 			$this->header('Location')
 		);
 	}
@@ -317,7 +325,7 @@ public function offsetExists($name) {
  * @return null
  */
 	public function offsetSet($name, $value) {
-		
+
 	}
 
 /**
@@ -327,7 +335,7 @@ public function offsetSet($name, $value) {
  * @return null
  */
 	public function offsetUnset($name) {
-		
+
 	}
 
 }