Update the dartdoc for HttpClient

sdk/lib/io/http.dart

Index: sdk/lib/io/http.dart
diff --git a/sdk/lib/io/http.dart b/sdk/lib/io/http.dart
index 9a54af20c27d0421de5a5aebcb119a3653b36218..26c1a4644bb4705cfda74cb52974c47ec0d227e6 100644
--- a/sdk/lib/io/http.dart
+++ b/sdk/lib/io/http.dart
@@ -688,17 +688,17 @@ abstract class HttpRequest implements Stream<List<int>> {
  * will be determined from the "charset" parameter of the
  * "Content-Type" header.
  *
- *   HttpResponse response = ...
- *   response.headers.contentType
- *       = new ContentType("application", "json", charset: "utf-8");
- *   response.write(...);  // Strings written will be UTF-8 encoded.
+ *     HttpResponse response = ...
+ *     response.headers.contentType
+ *         = new ContentType("application", "json", charset: "utf-8");
+ *     response.write(...);  // Strings written will be UTF-8 encoded.
  *
  * If no charset is provided the default of ISO-8859-1 (Latin 1) will
  * be used.
  *
- *   HttpResponse response = ...
- *   response.headers.add(HttpHeaders.CONTENT_TYPE, "text/plain");
- *   response.write(...);  // Strings written will be ISO-8859-1 encoded.
+ *     HttpResponse response = ...
+ *     response.headers.add(HttpHeaders.CONTENT_TYPE, "text/plain");
+ *     response.write(...);  // Strings written will be ISO-8859-1 encoded.
  *
  * If an unsupported encoding is used an exception will be thrown if
  * using one of the write methods taking a string.
@@ -762,13 +762,63 @@ abstract class HttpResponse implements IOSink<HttpResponse> {
 
 
 /**
- * HTTP client factory. The [HttpClient] handles all the sockets associated
- * with the [HttpClientConnection]s and when the endpoint supports it, it will
- * try to reuse opened sockets for several requests to support HTTP 1.1
- * persistent connections. This means that sockets will be kept open for some
- * time after a requests have completed, unless HTTP procedures indicate that it
- * must be closed as part of completing the request. Use [:HttpClient.close:]
- * to force close the idle sockets.
+ * The [HttpClient] class implements the client side of the HTTP
+ * protocol. It contains a number of methods to send a HTTP request
+ * to a HTTP server and receive a HTTP response back.
+ *
+ * This is handles as a two step process where two futures are

[Bill Hesse, 2013/04/09 07:56:27]

This is a two-step process, triggered by two futures.  When the first future
completes with a [HttpClientRequest], then HTTP headers and a body can be set on
the request, and [:close:] is called to sent it to the server.

The second future, the .response field of the request, completes with an
[HttpClientResponse] object when the
response is received from the server.  This object contains
the headers and body of the response.

The future HttpClientRequest is created by methods such as [getUrl] and [open].

[Bill Hesse, 2013/04/09 07:56:27]

"handled"

[Søren Gjesse, 2013/04/12 07:27:22]

Done.

[Søren Gjesse, 2013/04/12 07:27:22]

Rephrased as suggested.

+ * used. There is a future for when the request is ready and another
+ * future for when the response is received. When the request is ready

[Anders Johnsen, 2013/04/09 08:04:28]

Maybe add that a ready response means that a Socket is successfully connected.
That'll also make it clear that failed connections will fail here.

[Søren Gjesse, 2013/04/12 07:27:22]

Done.

+ * a [HttpClientRequest] object is provided where one can set HTTP
+ * headers and include a body in the request as well. The request
+ * object has a [:close:] that is called to send the request to the server.
+ *
+ * When the HTTP response is ready a [HttpClientResponse] object is
+ * provided which provide access to the headers and body of the response.

[Bill Hesse, 2013/04/09 07:56:27]

provides

[Søren Gjesse, 2013/04/12 07:27:22]

Done.

+ *
+ *     HttpClient client = new HttpClient();
+ *     client.getUrl(new Uri.fromString("http://www.example.com/"))
+ *         .then((HttpClientRequest request) {
+ *           // Prepare the request.
+ *
+ *           // Set handler for the response object.
+ *           request.response.then((HttpClientResponse response) {
+ *             // Process the response.
+ *           });
+ *
+ *           // Call close on the request to send it to the server.
+ *           request.close();
+ *         });
+ *
+ * The [:close:] method on the [HttpClientRequest] object also returns
+ * the future for the [HttpClientResponse]. This means that the code
+ * above can be written like this:
+ *
+ *     HttpClient client = new HttpClient();
+ *     client.getUrl(new Uri.fromString("http://www.example.com/"))
+ *         .then((HttpClientRequest request) {
+ *           // Prepare the request then call close on it to send it.
+ *           return request.close();
+ *         })
+ *         .then((HttpClientResponse response) {
+ *          // Process the response.
+ *         });
+ *
+ * All [HttpClient] request sets the following header by default:

[Bill Hesse, 2013/04/09 07:56:27]

requests set

[Anders Johnsen, 2013/04/09 08:04:28]

requests

[Søren Gjesse, 2013/04/12 07:27:22]

Done.

[Søren Gjesse, 2013/04/12 07:27:22]

Done.

+ *
+ *     Accept-Encoding: gzip
+ *
+ * This allows the HTTP server to use gzip compression for the body it

[Anders Johnsen, 2013/04/09 08:04:28]

it -> if

[Søren Gjesse, 2013/04/12 07:27:22]

Done.

+ * possible. If this behavior is not desired set the
+ * "Accept-Encoding" header to something else.
+ *
+ * The [HttpClient] handles all sockets associated HTTP requests and

[Bill Hesse, 2013/04/09 07:56:27]

caches all sockets associated with HTTP requests, and when the server supports
HTTP 1.1 persistent connections, it will reuse open sockets for several
requests.

[Anders Johnsen, 2013/04/09 08:04:28]

associated with

[Søren Gjesse, 2013/04/12 07:27:22]

Done.

[Søren Gjesse, 2013/04/12 07:27:22]

Done.

+ * when the server supports it, it will try to reuse opened sockets
+ * for several requests to support HTTP 1.1 persistent
+ * connections. This means that sockets will be kept open for some
+ * time after a requests have completed, unless HTTP procedures

[Bill Hesse, 2013/04/09 07:56:27]

unless the protocol requires the request to close the socket.
...
to shut down the HttpClient object and force the idle sockets to close.

[Søren Gjesse, 2013/04/12 07:27:22]

Done.

+ * indicate that it must be closed as part of completing the
+ * request. Use [:HttpClient.close:] to force close the idle sockets.
  */
 abstract class HttpClient {
   static const int DEFAULT_HTTP_PORT = 80;
@@ -906,17 +956,17 @@ abstract class HttpClient {
    * To activate this way of resolving proxies assign this function to
    * the [findProxy] property on the [HttpClient].
    *
-   *   HttpClient client = new HttpClient();
-   *   client.findProxy = HttpClient.findProxyFromEnvironment;
+   *     HttpClient client = new HttpClient();
+   *     client.findProxy = HttpClient.findProxyFromEnvironment;
    *
    * If you don't want to use the system environment you can use a
    * different one by wrapping the function.
    *
-   *   HttpClient client = new HttpClient();
-   *   client.findProxy = (url) {
-   *     return HttpClient.findProxyFromEnvironment(
-   *         url, {"http_proxy": ..., "no_proxy": ...});
-   *   }
+   *     HttpClient client = new HttpClient();
+   *     client.findProxy = (url) {
+   *       return HttpClient.findProxyFromEnvironment(
+   *           url, {"http_proxy": ..., "no_proxy": ...});
+   *     }
    */
   static String findProxyFromEnvironment(Uri url,
                                          {Map<String, String> environment}) {
@@ -951,17 +1001,17 @@ abstract class HttpClient {
  * encoding used will be determined from the "charset" parameter of
  * the "Content-Type" header.
  *
- *   HttpClientRequest request = ...
- *   request.headers.contentType
- *       = new ContentType("application", "json", charset: "utf-8");
- *   request.write(...);  // Strings written will be UTF-8 encoded.
+ *     HttpClientRequest request = ...
+ *     request.headers.contentType
+ *         = new ContentType("application", "json", charset: "utf-8");
+ *     request.write(...);  // Strings written will be UTF-8 encoded.
  *
  * If no charset is provided the default of ISO-8859-1 (Latin 1) will
  * be used.
  *
- *   HttpClientRequest request = ...
- *   request.headers.add(HttpHeaders.CONTENT_TYPE, "text/plain");
- *   request.write(...);  // Strings written will be ISO-8859-1 encoded.
+ *     HttpClientRequest request = ...
+ *     request.headers.add(HttpHeaders.CONTENT_TYPE, "text/plain");
+ *     request.write(...);  // Strings written will be ISO-8859-1 encoded.
  *
  * If an unsupported encoding is used an exception will be thrown if
  * using one of the write methods taking a string.