Improve the HttpClient documentation

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 925 matching lines @@
    * `Dart/<version> (dart:io)`.
    *
    * If the userAgent is set to `null`, no default `User-Agent` header will be
    * added to each request.
    */
   String userAgent;
 
   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
-   * the request will be set to the value [host]:[port]. This can be overridden
-   * through the [HttpClientRequest] interface before the request is sent.
-   * NOTE if [host] is an IP address this will still be set in the 'host'
+   * Opens a HTTP connection.
+   *
+   * The HTTP method to use is specified in [method], the server is
+   * specified using [host] and [port], and the path is specified
+   * using [path].
+   *
+   * The `Host` header for the request will be set to the value
+   * [host]:[port]. This can be overridden through the
+   * [HttpClientRequest] interface before the request is sent.  NOTE
+   * if [host] is an IP address this will still be set in the `Host`
    * header.
+   *
+   * For additional information on when the returned future completes,
+   * and the flow of the HTTP request, see the overall documentation

[Bill Hesse, 2013/08/01 08:33:31]

Would

completes, and on using the HttpClientRequest that it completes with, see the

or

For additional information on the sequence of events during an HTTP transaction,
and the objects returned by the futures, see the

be better?

[Søren Gjesse, 2013/08/01 09:25:59]

Yes, thanks (picked the second one).

+   * for the class [HttpClient].
    */
   Future<HttpClientRequest> open(String method,
                                  String host,
                                  int port,
                                  String path);
 
   /**
-   * Opens a HTTP connection. The returned [HttpClientRequest] is used to
-   * fill in the content of the request before sending it. The 'hosth header for
-   * the request will be set to the value [host]:[port]. This can be overridden
-   * through the [HttpClientRequest] interface before the request is sent.
-   * NOTE if [host] is an IP address this will still be set in the 'host'
+   * Opens a HTTP connection.
+   *
+   * Tht HTTP method is specified in [method] and the URL to use in
+   * [url].
+   *
+   * The `Host` header for the request will be set to the value
+   * [host]:[port]. This can be overridden through the
+   * [HttpClientRequest] interface before the request is sent.  NOTE
+   * if [host] is an IP address this will still be set in the `Host`
    * header.
+   *
+   * For additional information on when the returned future completes,
+   * and the flow of the HTTP request, see the overall documentation
+   * for the class [HttpClient].
    */
   Future<HttpClientRequest> openUrl(String method, Uri url);
 
   /**
-   * Opens a HTTP connection using the GET method. See [open] for
-   * details. Using this method to open a HTTP connection will set the
-   * content length to 0.
+   * Opens a HTTP connection using the GET method.
+   *
+   * The server is specified using [host] and [port], and the path is
+   * specified using [path].

[Bill Hesse, 2013/08/01 08:33:31]

path (and possible query)
?

[Søren Gjesse, 2013/08/01 09:25:59]

Done, added fragment as well.

+   *
+   * See [open] for details.
    */
   Future<HttpClientRequest> get(String host, int port, String path);
 
   /**
-   * Opens a HTTP connection using the GET method. See [openUrl] for
-   * details. Using this method to open a HTTP connection will set the
-   * content length to 0.
+   * Opens a HTTP connection using the GET method.
+   *
+   * The URL to use is specified in [url].
+   *
+   * See [openUrl] for details.
    */
   Future<HttpClientRequest> getUrl(Uri url);
 
   /**
-   * Opens a HTTP connection using the POST method. See [open] for details.
+   * Opens a HTTP connection using the POST method.
+   *
+   * The server is specified using [host] and [port], and the path is
+   * specified using [path].
+   *
+   * See [open] for details.
    */
   Future<HttpClientRequest> post(String host, int port, String path);
 
   /**
-   * Opens a HTTP connection using the POST method. See [openUrl] for details.
+   * Opens a HTTP connection using the POST method.
+   *
+   * The URL to use is specified in [url].
+   *
+   * See [openUrl] for details.
    */
   Future<HttpClientRequest> postUrl(Uri url);
 
   /**
    * Sets the function to be called when a site is requesting
    * authentication. The URL requested and the security realm from the
    * server are passed in the arguments [url] and [realm].
    *
    * The function returns a [Future] which should complete when the
    * authentication has been resolved. If credentials cannot be
@@ skipping 436 matching lines @@
 
 class RedirectException implements HttpException {
   final String message;
   final List<RedirectInfo> redirects;
 
   const RedirectException(String this.message,
                           List<RedirectInfo> this.redirects);
 
   String toString() => "RedirectException: $message";
 }