Document the HttpClient uses KeepAlive, keeping sockets open for up to 60 seconds after a connectio…

runtime/bin/http.dart

 // Copyright (c) 2012, 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.
 
 /**
  * HTTP status codes.
  */
 interface HttpStatus {
   static final int CONTINUE = 100;
   static final int SWITCHING_PROTOCOLS = 101;
@@ skipping 605 matching lines @@
    * operations on it.
    *
    * This is normally used when a HTTP upgrade request is received
    * and the communication should continue with a different protocol.
    */
   DetachedSocket detachSocket();
 }
 
 
 /**
- * HTTP client factory.
+ * 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.shutdown:]
+ * to force close the idle sockets.
  */
 interface HttpClient default _HttpClient {
   static final int DEFAULT_HTTP_PORT = 80;
 
   HttpClient();
 
   /**
    * Opens a HTTP connection. The returned [HttpClientConnection] is
    * used to register callbacks for asynchronous events on the HTTP
    * connection. The "Host" header for the request will be set to the
@@ skipping 258 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);
 }