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 a two-step process, triggered by two futures. When the
+ * first future completes with a [HttpClientRequest] the underlying
+ * network connection has been established, but no data has yet been
+ * sent. The HTTP headers and body can be set on the request, and
+ * [:close:] is called to sent it to the server.
+ *
+ * The second future, is returned by [:close:], completes with an

[Bill Hesse, 2013/04/12 08:26:00]

future, which is returned ...

[Søren Gjesse, 2013/04/12 08:28:37]

Done.

+ * [HttpClientResponse] object when the response is received from the
+ * server. This object contains the headers and body of the response.
+
+ * The future for [HttpClientRequest] is created by methods such as
+ * [getUrl] and [open].
+ *
+ * When the HTTP response is ready a [HttpClientResponse] object is
+ * provided which provides access to the headers and body of the response.
+ *
+ *     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] requests set the following header by default:
+ *
+ *     Accept-Encoding: gzip
+ *
+ * This allows the HTTP server to use gzip compression for the body if
+ * possible. If this behavior is not desired set the
+ * "Accept-Encoding" header to something else.
+ *
+ * The [HttpClient] supports persistent connections and caches network
+ * connections to reuse then for multiple requests whenever
+ * possible. This means that network connections can be kept open for
+ * some time after a request have completed. Use [:HttpClient.close:]
+ * to force shut down the [HttpClient] object and close the idle
+ * network connections.
  */
 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);
 }