Update the dartdoc for HttpClient

sdk/lib/io/http.dart

 // Copyright (c) 2013, the Dart project authors.  Please see the AUTHORS file
 // for details. All rights reserved. Use of this source code is governed by a
 // BSD-style license that can be found in the LICENSE file.
 
 part of dart.io;
 
 /**
  * HTTP status codes.
  */
 abstract class HttpStatus {
@@ skipping 670 matching lines @@
  * header of the response. When the header has been set up the methods
  * from the [IOSink] can be used to write the actual body of the HTTP
  * response. When one of the [IOSink] methods is used for the
  * first time the request header is send. Calling any methods that
  * will change the header after it is sent will throw an exception.
  *
  * When writing string data through the [IOSink] the encoding used
  * 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.
  */
 abstract class HttpResponse implements IOSink<HttpResponse> {
   // TODO(ajohnsen): Add documentation of how to pipe a file to the response.
   /**
    * Gets and sets the content length of the response. If the size of
    * the response is not known in advance set the content length to
    * -1 - which is also the default if not set.
@@ skipping 43 matching lines @@
 
   /**
    * Gets information about the client connection. Returns [null] if the socket
    * is not available.
    */
   HttpConnectionInfo get connectionInfo;
 }
 
 
 /**
- * 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;
   static const int DEFAULT_HTTPS_PORT = 443;
 
   factory HttpClient() => new _HttpClient();
 
   /**
    * Opens a HTTP connection. The returned [HttpClientRequest] is used to
    * fill in the content of the request before sending it. The 'host' header for
@@ skipping 117 matching lines @@
    *
    * [:no_proxy:] and [:NO_PROXY:] specify a comma separated list of
    * postfixes of hostnames for which not to use the proxy
    * server. E.g. the value "localhost,127.0.0.1" will make requests
    * to both "localhost" and "127.0.0.1" not use a proxy. If both are set
    * the lower case one takes precedence.
    *
    * 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}) {
     return _HttpClient._findProxyFromEnvironment(url, environment);
   }
 
   /**
    * Shutdown the HTTP client. If [force] is [:false:] (the default)
    * the [:HttpClient:] will be kept alive until all active
    * connections are done. If [force] is [:true:] any active
@@ skipping 14 matching lines @@
  * header of the request. When the header has been set up the methods
  * from the [IOSink] can be used to write the actual body of the HTTP
  * request. When one of the [IOSink] methods is used for the first
  * time the request header is send. Calling any methods that will
  * change the header after it is sent will throw an exception.
  *
  * When writing string data through the [IOSink] the
  * 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.
  */
 abstract class HttpClientRequest
     implements IOSink<HttpClientRequest> {
   /**
    * Gets and sets the content length of the request. If the size of
    * the request is not known in advance set content length to -1,
    * which is also the default.
@@ skipping 244 matching lines @@
 class RedirectLimitExceededException extends RedirectException {
   const RedirectLimitExceededException(List<RedirectInfo> redirects)
       : super("Redirect limit exceeded", redirects);
 }
 
 
 class RedirectLoopException extends RedirectException {
   const RedirectLoopException(List<RedirectInfo> redirects)
       : super("Redirect loop detected", redirects);
 }